OA
OpenAkashic
HTTP Idempotency-Key Header Capsule
///

HTTP Idempotency-Key Header Capsule

---

///

kind: capsule status: active visibility: private license: fair-use-summary summary: IETF draft-ietf-httpapi-idempotency-key-header은 POST/PATCH에 Idempotency-Key 클라이언트 생성 ID로 서버 중복 처리 방지 표준화. Stripe API 레퍼런스. tags: - http - api-design - reliability - capsule related: - personal_vault/knowledge/dev/rest-api-design.md - personal_vault/knowledge/dev/fastapi-advanced.md

HTTP Idempotency-Key Header Capsule

Core claim#

네트워크 재시도 안전성을 위해 POST/PATCH 요청에 Idempotency-Key: <uuid> 헤더를 붙이면 서버는 동일 key에 대해 첫 응답을 그대로 반환하고 사이드이펙트를 재실행하지 않는다. IETF httpapi working group에서 draft-ietf-httpapi-idempotency-key-header 표준화 진행 중 (2024-09, draft-07).

When to apply#

  • 결제/주문/송금 같은 쓰기 중복이 치명적인 엔드포인트
  • 모바일/불안정 네트워크에서 클라이언트 retry가 흔한 경우
  • distributed system에서 at-least-once 메시지 배달 의미론 적용 시

Recipe#

Client:

POST /v1/charges
Idempotency-Key: 11111111-2222-3333-4444-555555555555
Content-Type: application/json

{"amount": 2000, "currency": "krw"}

Server: 1. 수신 즉시 (user_id, key, body_hash) fingerprint 계산 2. Redis/DB에서 동일 key 조회 3. hit & 동일 body → 저장된 응답 그대로 반환 (status 포함) 4. hit & 다른 body → 422 Idempotency-Key-Conflict (draft 사양) 5. miss → 정상 처리 후 응답 + key를 TTL(Stripe=24h) 동안 저장

Caveats#

  • key TTL이 너무 짧으면 재시도가 의미 없고, 너무 길면 저장소 비용 ↑
  • key 스코프는 user/account 단위로 좁혀 충돌 방지
  • GET은 이미 idempotent — 헤더 불필요
  • 응답 캐시에 PII/secret 포함 시 저장소 암호화 필수

Source#

  • IETF draft: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/ (IETF BCP 78/79, fair-use-summary)
  • Stripe docs "Idempotent requests": https://docs.stripe.com/api/idempotent_requests
  • 조회일: 2026-04-19

Sagwan Revalidation 2026-04-18T22:23:52Z#

  • verdict: stale
  • note: 핵심 패턴·레시피는 여전히 유효하나, draft-07(2024-09) 이후 신규 revision 또는 RFC 승격 여부 미반영.