중복 요청 비교

첫 요청만 실행하고, 재시도는 같은 결과로 되돌립니다.

멱등성의 핵심은 요청 횟수를 줄이는 것이 아니라, 같은 의도가 여러 번 도착해도 데이터베이스의 최종 상태가 한 번만 바뀌게 만드는 것입니다.

두 요청이 같은 작업인지 구분하는 기준

Idempotency-Key: pay:order-42

저장소는 이 키를 기준으로 첫 실행과 이미 처리된 재시도를 나눕니다.

비교 축	첫 요청	같은 요청 재시도
저장소가 보는 상태	아직 처리 기록이 없다 같은 키로 저장된 결과가 없으므로, 이 요청은 실행 대상으로 판단됩니다.	이미 처리된 기록이 있다 같은 키가 이미 남아 있으므로, 이 요청은 재실행 금지 경로로 이동합니다.
DB 상태 변화	PENDING → PAID 결제 row를 한 번 생성하고 주문 상태를 완료로 바꿉니다. 효과는 여기서 단 한 번 발생합니다.	PAID 유지 추가 INSERT나 상태 변경 없이 기존 결과만 읽습니다. 중복 결제가 생기지 않습니다.
클라이언트 응답	새 결과를 저장한 뒤 반환 생성된 payment_id와 처리 결과를 함께 저장해, 이후 재시도가 같은 값을 받을 수 있게 합니다.	저장된 응답을 그대로 재사용 타임아웃 뒤 재시도가 와도, 서버는 기존 성공 결과를 다시 돌려주고 비즈니스 로직은 다시 돌리지 않습니다.

비교 축

첫 요청

같은 요청 재시도

저장소가 보는 상태

아직 처리 기록이 없다

같은 키로 저장된 결과가 없으므로, 이 요청은 실행 대상으로 판단됩니다.

이미 처리된 기록이 있다

같은 키가 이미 남아 있으므로, 이 요청은 재실행 금지 경로로 이동합니다.

DB 상태 변화

PENDING → PAID

결제 row를 한 번 생성하고 주문 상태를 완료로 바꿉니다. 효과는 여기서 단 한 번 발생합니다.

PAID 유지

추가 INSERT나 상태 변경 없이 기존 결과만 읽습니다. 중복 결제가 생기지 않습니다.

클라이언트 응답

새 결과를 저장한 뒤 반환

생성된 payment_id와 처리 결과를 함께 저장해, 이후 재시도가 같은 값을 받을 수 있게 합니다.

저장된 응답을 그대로 재사용

타임아웃 뒤 재시도가 와도, 서버는 기존 성공 결과를 다시 돌려주고 비즈니스 로직은 다시 돌리지 않습니다.

결론

멱등성은 재시도를 허용하면서도 효과는 한 번으로 제한하는 계약입니다. 같은 요청이라면 “다시 처리”가 아니라 “기존 결과 조회”로 수렴해야 합니다.