멱등성
멱등성 키를 사용하여 중복 리소스 생성 없이 안전하게 POST 요청을 재시도할 수 있습니다.
동작 방식
POST 요청에 고유한 값(UUID 권장)과 함께 Idempotency-Key 헤더를 포함하세요. 동일한 키가 24시간 이내에 다시 전송되면, API는 작업을 재실행하지 않고 캐시된 원본 응답을 반환합니다.
curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{id}/checkout \
-H "Authorization: Bearer pk_test_your_key" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"email": "customer@example.com", "payment_provider": "stripe"}'
사용 시점
멱등성 키는 중복되면 안 되는 작업에 권장됩니다:
| 엔드포인트 | 이유 |
|---|
POST /storefront/carts/{id}/checkout | 중복 주문 방지 |
POST /admin/orders/{id}/payments | 중복 결제 방지 |
POST /admin/orders/{id}/refunds | 이중 환불 방지 |
키 규칙
- 키는 요청마다 고유해야 합니다 — UUID를 사용하세요
- 키는 스토어(API 키) 단위로 적용됩니다
- 캐시된 응답은 24시간 후 만료됩니다
- 성공 응답(2xx)만 캐시됩니다
- 동일한 키로 다른 요청 본문을 보내면 원본 캐시된 응답이 반환됩니다
Idempotency-Key 헤더는 선택 사항입니다. 생략하면 멱등성 보호 없이 정상적으로 요청이 처리됩니다.
