A timeout does not tell the client whether the write happened#
A payment client sends a create request, the server commits it, and the response is lost. Retrying is necessary for reliability, but repeating the business operation could charge twice.
POST /payments
Idempotency-Key: 7f92...The server must enforce the key#
Bind the key to a caller and a normalized request identity. Atomically establish one operation, retain its outcome for a documented period, and return the same result for a valid duplicate. Reject reuse with incompatible parameters.
Concurrent duplicates need one winner or a shared in-progress state. Retention must cover the client's retry window without keeping keys forever. The business transition itself still needs constraints; a header cannot magically make arbitrary logic idempotent.
Use these prompts to extend the design. The useful answer is a reasoned change, not a memorized sentence.
- What is stored before the operation finishes?
- How do concurrent requests with the same key behave?
- What if the key is reused with a different amount?
- How long is an outcome retained?
- Which downstream side effects also need deduplication?
Later, the canonical Reliability Idempotency lesson goes deeper into state transitions and side effects.
Related practice problems
Use the manifest-backed prompts below to apply this lesson in a complete design.
- RFC 9110: HTTP SemanticsIETF / RFC Editor