Idempotency

케이스 1토스페이먼츠 — 결제 API 멱등키

토스페이먼츠는 모든 POST API에서 멱등키 헤더를 받습니다. 멱등성은 키와 API 키, API 주소, HTTP 메서드의 조합으로 구분되므로 같은 키라도 다른 엔드포인트면 별개로 봅니다. 키 값은 UUID 같은 무작위 문자열을 권장합니다.
도입효과: 멱등키 유효기간 최초 요청일로부터 15일, 키 최대 길이 300자, 처리 중 중복 요청 시 HTTP 409 반환^[4][5]

케이스 2스트라이프 — 결제 API

스트라이프는 첫 요청의 응답 코드와 본문을 성공 여부와 관계없이 저장해 두고, 같은 키로 다시 오면 그 저장본을 돌려줍니다. 들어온 파라미터가 처음과 다르면 오류로 막습니다. GET과 DELETE는 정의상 멱등하므로 키가 필요 없습니다.
도입효과: 멱등키 보관 기간 최소 24시간, 키 최대 길이 255자, 적용 범위 모든 POST 요청^[3]

케이스 3카카오페이 — MSA 네트워크 예외 처리

카카오페이는 네트워크 예외가 나면 요청이 닿지 않았는지, 성공했는데 응답만 잃었는지, 실패했는지 구분할 수 없다는 점을 출발점으로 삼았습니다. 거래별 고유 키를 두고 복구 경로를 따로 만들었습니다. 무한 재시도가 보상 트랜잭션 실패로 번지는 것을 막기 위해서입니다.
도입효과: 타임아웃 시 재시도 횟수 1회로 제한한 뒤 미확인 상태로 전이(2022-05-25)^[6]

케이스 4AWS — EC2 API 클라이언트 토큰

AWS EC2 API는 클라이언트 토큰 파라미터로 멱등성을 제공합니다. 일부 동작은 토큰 없이도 기본적으로 멱등합니다. 이미 완료된 요청을 같은 토큰과 같은 파라미터로 다시 보내면 추가 동작 없이 성공으로 처리됩니다.
도입효과: 클라이언트 토큰 최대 길이 64자(ASCII), 파라미터 불일치 시 IdempotentParameterMismatch 오류 반환^[7]

오늘 바로 해보기
1. 우리 API 중 중복 실행되면 곰란한 POST 엔드포인트를 하나 고릅니다.
2. 클라이언트가 요청마다 UUID를 만들어 헤더에 넣도록 규칙을 정합니다.
3. 서버는 키와 응답 코드, 본문을 저장하고 같은 키가 오면 저장본을 돌려줍니다.
4. 같은 키에 다른 본문이 오면 오류로 막습니다.
5. 키 보관 기간을 정해 만료 삭제 작업을 등록합니다.

한계와 진화
멱등키 헤더는 아직 표준이 아닙니다. IETF의 Idempotency-Key 헤더 문서는 초안 상태로 2026년 4월 18일 만료됐습니다. 그래서 규칙은 서비스마다 다릅니다. 보관 기간은 24시간·15일·미명시로, 키 길이는 255자·300자·64자로 갈립니다. 결제대행사를 바꾸면 같은 구현을 그대로 옮겨 쓸 수 없습니다.

멱등하다고 응답까지 같은 것은 아닙니다. RFC 9110은 멱등성을 서버에 남는 의도된 효과로 한정하므로, 제대로 만든 DELETE도 첫 번째는 204를, 두 번째는 404를 돌려줄 수 있습니다. 스트라이프도 결과 저장은 엔드포인트 실행이 시작된 뒤에만 이뤄지므로 검증 실패나 동시 충돌은 클라이언트가 다시 시도해야 한다고 명시합니다. 재시도 규칙을 문서로 박아 두는 일이 같이 가야 합니다.