Idempotency & Retry-Safe Systems · Idempotency Keys in Practice
The Idempotency-Key Pattern
How clients and servers use keys to deduplicate unsafe requests.
The client generates a unique key (UUIDv4/v7) per logical operation and sends it in the Idempotency-Key header (IETF HTTPAPI draft). The server records the key with the outcome; repeated requests with the same key return the stored response instead of re-executing. Keys are scoped per client/account, expire after a window (commonly 24 h), and should be passed downstream (e.g., to payment providers) so the whole chain is idempotent. Stripe, Adyen, PayPal and many fintech APIs use this pattern.
Server behavior (per the IETF draft)
| Situation | Server response |
|---|---|
| New key | Process, store result, return it |
| Same key, same request, completed | Return stored status + body |
| Same key, request still processing | 409 Conflict (retry later) |
| Same key, different request body | 422 Unprocessable Content |
| Missing key on endpoint that requires it | 400 Bad Request |
| Expired key reused | Treated as new request (document the window) |
POST /v1/payments HTTP/1.1
Idempotency-Key: 01J9ZQ3K8V4Y2C1T6M0F5N7B9R
Content-Type: application/json
{"amount": 2500, "currency": "EUR", "source": "tok_visa"}
→ 201 Created {"id": "pay_1", "status": "succeeded"}
(network drops; client retries with the SAME key)
→ 201 Created {"id": "pay_1", "status": "succeeded"} ← replayed, no second charge
Idempotent-Replayed: true
Common pitfalls
- Generating a new key per retry (defeats the purpose).
- Global key scope (collisions between clients).
- Not documenting the expiry window.
Key points
- One key per logical operation
- Store and replay the outcome
- Scope per client; expire; propagate downstream
Further reading: IETF draft: The Idempotency-Key HTTP Header Field
Practice questions
When should the client generate a new idempotency key?
Answer
Only for a new logical operation (e.g., the user submits a new payment). All retries of the same operation must reuse the same key.
Why scope keys per account or API key?
Answer
Different clients might generate the same key; scoping prevents one client's request from replaying another's stored response.
Open in the app to mark lessons complete, take notes and track your progress.