API Idempotency Key 생명주기 설계

Idempotency는 흔히 “같은 요청을 두 번 보내도 한 번만 처리된다”로 설명되지만, 운영에서 더 어려운 질문은 그 약속을 얼마나 오래 기억할지, 그리고 무엇을 같은 요청으로 볼지입니다.

개념보다 생명주기가 더 중요하다

팀은 최소한 다음 질문에 답할 수 있어야 합니다.

이 규칙이 없으면 idempotency는 부분적인 안전장치에 그칩니다.

좋은 key는 단순한 중복 요청 식별자가 아니라 하나의 논리적 비즈니스 시도를 표현해야 합니다. 그래서 보통 다음을 함께 저장합니다.

이렇게 해야 우연한 key 재사용이 엉뚱한 결과를 돌려주지 않습니다.

TTL이 너무 짧으면 중복 재시도가 보호 창을 벗어날 수 있습니다. 반대로 너무 길면 비싼 상태를 오래 들고 가고, replay 동작도 예측하기 어려워집니다.

좋은 TTL은 보통 비즈니스 의미와 함께 정합니다.

같은 key가 다시 왔을 때 API가 무엇을 돌려주는지는 명확해야 합니다.

가장 안전한 시스템은 replay를 구현 세부사항이 아니라 API 계약의 일부로 다룹니다.

긴 작업을 HTTP 요청 하나로 끝내지 않고 작업 생성, 재시도, 취소, 결과 조회까지 안정적으로 설계하는 방법을 정리합니다.

오래 걸리는 백엔드 작업을 동기 API로만 다루면 사용자 경험과 운영 안정성이 함께 흔들립니다. Job status 패턴을 실전적으로 정리합니다.

TypeScript, Python, Java 같은 언어에서 정적 타입만으로 막기 어려운 외부 입력을 런타임 스키마로 보호하는 방법을 정리합니다.

백필은 한 번에 끝나지 않는 경우가 많습니다. 중단과 재시작을 견디는 체크포인트 설계가 데이터 작업의 안정성을 좌우합니다.