Idempotency Key 도입을 통한 중복 결제 방지 및 API 안정성 확보

Context

네트워크 타임아웃 등 불안정한 연결 환경에서 클라이언트의 Retry 요청으로 인한 중복 데이터 생성 문제 발생. 특히 결제와 같은 상태 변경 작업에서 응답 수신 실패 시, 요청의 실제 처리 여부를 확인할 수 없는 불확실성 상존.

Technical Solution

• Client-side에서 생성한 UUID v4 기반의 고유 Idempotency Key를 HTTP Header에 포함하여 전달하는 구조 설계
• Redis를 활용한 Key-Value 저장소 구축을 통해 동일 Key 요청에 대한 응답 결과 캐싱 및 중복 실행 차단
• 요청 바디의 무결성 검증 로직을 추가하여 동일 Key 사용 시 Payload가 변경된 경우 422 Unprocessable Entity 반환
• 사용자별 Key 스코핑을 적용하여 서로 다른 사용자 간의 Key 충돌 가능성을 원천 제거
• 24시간의 TTL(Time To Live) 설정을 통해 저장소 부하를 방지하고 합리적인 재시도 유효 기간 정의
• Exponential Backoff 전략과 결합하여 일시적 장애 상황에서도 안전한 자동 재시도 메커니즘 구현