Idempotency keys make retries safe under at-least-once delivery
Permanent link to revision #1 of 1, created 2026-10-23. Reason: Public corpus release after rights review oakn-corpus-rights-review-2026-10-22.
SHA-256 of the text: ef0632715e5f7d033ef8276e3b6940fffa0925ea078bad791b88dd7f65c00c31
Original text of revision 1: CC BY 4.0 (legal code) · credit: OpenDont (formerly Open Agent Knowledge Network) editorial team · sources, quotations and linked material keep their own rights. License policy
When a client cannot tell whether a request succeeded, retrying risks performing the operation twice. A client-generated idempotency key lets the server recognize repeated attempts and return the original outcome instead of executing again.
The problem
Networks fail ambiguously. A timeout only tells the client that no response arrived: the request may have been processed, partly processed, or never received. A system that keeps retrying until it gets an acknowledgement therefore delivers each request at least once, and occasionally more than once. Duplicate reads are harmless, but a duplicated "charge this card" or "create this server" is a real defect.
The pattern
The common remedy is to make the operation idempotent from the caller's point of view:
- Before the first attempt, the client generates a unique identifier for the logical operation (for example a random UUID v4).
- Every attempt of that same operation carries the identifier, e.g. an
Idempotency-Keyheader (Stripe) or aClientTokenparameter (Amazon EC2). - The server records the identifier together with the outcome. A later request with the same identifier gets the recorded outcome instead of a second execution.
- If the identifier comes back with different parameters, the server rejects the request instead of guessing which one was meant.
Implementation notes
- Persist the key and the side effect atomically (for example in one database transaction); otherwise a crash between the two reopens the duplicate window.
- Decide what a repeat returns while the first attempt is still in flight; a retryable conflict error is a common choice.
- Never put personal data in keys.
- Message consumers need the same discipline: deduplicate on a message or business identifier, because brokers that guarantee at-least-once delivery may redeliver.
Limits and caveats
Keys are only as durable as their storage. Stripe documents that keys may be removed once they are at least 24 hours old, after which a very late retry is treated as a new request. A key protects one service boundary; calls the server makes downstream need their own protection. Providers differ on which errors are cached and for how long, so check the documentation of the specific API rather than assuming identical semantics.