문제: 재시도는 쉬운데 중복 방지는 왜 자주 빠질까

네트워크 환경이 불안정하면 클라이언트는 같은 요청을 다시 보냅니다. 이때 서버가 중복 요청을 구분하지 못하면 주문이 두 번 생성되거나, 결제가 중복 승인되는 문제가 발생할 수 있습니다.

문서가 “실패하면 재시도하세요”만 안내하면, 독자는 재시도 자체가 안전한지 판단할 수 없습니다. 결과적으로 기능보다 문서 신뢰도부터 떨어집니다.

원칙: Retry 가능성과 Idempotency 보장을 분리해 문서화하기

이 상황에서 핵심 기준은 재시도 가능성(retryability)과 멱등성(idempotency)을 분리해 설명하는 것입니다.

  • 재시도 가능성: 요청을 다시 보내도 되는지
  • 멱등성 보장: 같은 의도의 요청이 여러 번 도착해도 결과가 하나로 유지되는지

Idempotency-Key는 같은 작업 의도를 식별하는 키입니다. 클라이언트가 요청마다 고유 키를 생성해 헤더로 보내고, 서버가 키와 응답 결과를 일정 시간 저장하면 중복 처리를 제어할 수 있습니다.

문서에 반드시 명시할 3가지

문서에 최소한 아래 3가지를 명시해야 합니다.

  1. 어떤 엔드포인트가 Idempotency-Key를 요구하는지
  2. 키 유효 시간(TTL)과 저장 범위(사용자 단위/테넌트 단위)
  3. 동일 키 재요청 시 응답 규칙(기존 결과 재사용, 충돌 코드 반환 등)

이 정보가 있어야 검색 유입 독자도 로컬/스테이징 환경에서 중복 요청 시나리오를 재현하고 검증할 수 있습니다.

실전 예시: Idempotency-Key 요청/서버 처리 규칙

요청 예시:

curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1f0f97f6-ccde-4f10-86f4-4e4ad5e3d9b7" \
  -d '{"productId":"sku_123","quantity":1}'

서버 처리 흐름 최소 예시(의사코드)

1) (userId, idempotencyKey) 조회
2) 기존 성공 응답이 있으면 그대로 반환
3) 없으면 비즈니스 로직 실행 후 결과 저장
4) 동일 키로 payload가 다르면 409 Conflict 반환

문서에 함께 적으면 좋은 운영 기준

  • 키는 UUID 등 충분히 충돌 가능성이 낮은 값 사용
  • 같은 키를 다른 payload에 재사용하지 않음
  • 서버 로그에서 idempotencyKey를 검색 가능하게 필드화

이렇게 작성하면 독자는 “재시도하면 중복될 수 있음”이 아니라 “이 조건에서는 중복이 방지됨”을 확인할 수 있고, 문서 신뢰도가 자연스럽게 올라갑니다.

요약: 규칙이 분명할수록 재시도는 안전해진다

API 재시도 안내는 문장보다 규칙이 중요합니다. Idempotency-Key의 대상 엔드포인트, TTL, 재요청 응답 정책을 명확히 문서화하면 중복 요청 리스크를 줄이고 검증 가능한 가이드를 제공할 수 있습니다. 이 일관성이 기술 글의 SEO 신뢰도를 높이는 핵심입니다.

내부 링크