멱등 키는 얼마나 오래 보관해야 할까

결제나 주문 API에 멱등 키를 쓰면 같은 요청의 중복 처리를 막을 수 있습니다. 그러나 키를 영원히 보관할 수도 없고 너무 빨리 지우면 늦게 온 재시도가 새 작업으로 실행될 수 있습니다. 보관 기간은 재시도 방식과 업무 위험을 함께 보고 정해야 합니다.

멱등 키의 범위를 정의한다

키만 같다고 모든 요청을 같은 작업으로 취급하면 안 됩니다. 고객·엔드포인트·요청 본문의 의미를 묶어 비교하고, 같은 키에 다른 내용이 오면 충돌로 거절해야 합니다.

재시도 지연의 꼬리를 본다

네트워크 즉시 재시도뿐 아니라 작업 큐의 지수 백오프, 외부 파트너의 재전송, 수동 재처리가 며칠 뒤 도착할 수 있습니다. 가장 긴 합리적 재시도 기간이 키 보관 기간의 출발점입니다.

만료 뒤에도 업무 키를 지킨다

멱등 기록이 만료되면 기술적으로 같은 요청을 새로 받게 됩니다. 주문 번호나 결제 거래 번호처럼 업무 고유성이 있는 값에 별도 유니크 제약을 두면 만료 뒤 중복 실행의 마지막 안전망이 됩니다.

응답과 상태를 함께 저장한다

처리 완료 여부만 기록하면 재시도 고객에게 어떤 결과를 돌려줘야 할지 모릅니다. 최초 요청의 상태 코드와 안전한 응답 식별자를 저장하고, 처리 중인 요청과 완료된 요청을 구분해야 합니다.

보관 비용과 위험을 같이 측정한다

키 저장소 크기, 만료 정리 실패, 중복 시도 수를 모니터링합니다. 짧은 보관은 비용을 줄이지만 재시도 창보다 짧아서는 안 됩니다. API 제공자마다 정책이 다르므로 외부 서비스의 기간을 그대로 복사하지 않습니다.

현장에 적용할 때의 순서

1. 멱등 키 범위와 요청 본문 비교 규칙 정의
2. 가장 긴 재시도 창과 보관 기간 정합성 확인
3. 업무 고유키로 만료 후 중복 방지

주의할 실패: 멱등 저장소만 있으면 영구 중복 방지라고 오해

관찰할 지표: 중복 실행 건수·키 충돌·저장소 증가량

적용 전 체크리스트

• 최장 재시도 창과 수동 재처리 절차를 조사한다
• 같은 키·다른 요청 본문을 충돌 처리한다
• 만료 후 업무 고유키가 중복 실행을 막는지 테스트한다

참고 자료

Stripe API — Idempotent Requests. 멱등 키와 재시도 처리의 구체적 사례는 Stripe 공식 문서를 참고했습니다. 적정 보관 기간은 시스템별 재시도·업무 정책에 따라 달라집니다.

이미지와 도식은 이해를 돕기 위한 개념 시각화입니다. 특정 고객의 실제 설비·데이터·화면을 재현한 것이 아닙니다.

#멱등성 #Idempotency #API설계 #재시도 #중복방지 #결제API #주문처리 #트랜잭션 #분산시스템 #운영