The response can be lost after the effect succeeds#
A payment commits, but the client times out before receiving the response. The client cannot infer failure. Retrying without an idempotency contract can charge twice.
POST /payments
Idempotency-Key: payment-attempt-9382The service records a scoped key, request identity or hash, operation status, and result. The same valid key reuses the original outcome. A natural identifier such as refund_request_id or order_id + operation can enforce the same business invariant.
- Failure
- Two callers submit the same key concurrently
- Impact
- Both may execute the side effect
- Detection
- Unique-key conflict or in-progress record
- Mitigation
- Atomically claim the key with the business transition, then persist the result
- Trade-off
- Records need retention, conflict semantics, and recovery for incomplete work
Use these prompts to extend the design. The useful answer is a reasoned change, not a memorized sentence.
- What scope makes the key unique?
- What if the same key carries a different payload?
- What happens after retention expires?
- How does an in-progress duplicate wait or respond?
Related practice problems
Use the manifest-backed prompts below to apply this lesson in a complete design.
- Making retries safe with idempotent APIsAmazon Builders' Library
Reach this point to mark the lesson as read.