2026-09-29 · 6 min read · Rahul Chitturi
- http
- api
- retries
An Idempotency-Key lets a client retry a request that may have succeeded when the response was lost. The server stores the outcome for that key and replays it instead of charging, emailing, or creating a second resource.
Retries still duplicate work when the key is not scoped, the stored result expires too soon, or a second request reuses the key with a different body. The header is only a hint until persistence and comparison are explicit.
Define the key before the side effect
Record the header name, the raw key, the authenticated caller, the route, the request fingerprint, and whether a previous response exists. Generate the key once per user action and send that same value on every retry.
- Scope keys by caller and operation, not globally.
- Fingerprint the body and relevant headers.
- Persist the outcome before acknowledging success.
- Return the original response for an exact duplicate.
Separate replay, conflict, and expiry
An exact retry should return the stored status and body. The same key with a different payload is a conflict, not a second success. If the first request is still running, a duplicate should wait or return a documented in-progress result rather than starting another transaction.
After the retention window, a reused key is a new request. Clients that retry past expiry need a fresh key or they will look like a new purchase. Align client retry budgets with the server's storage lifetime.
Prove one action survives a lost response
Use Flashman's UUID generator for synthetic keys, the timestamp converter for expiry, the JSON formatter for stored responses, and diff to compare the original request with the retry.
Test a lost success response, a retry with the same body, a retry with a changed body, concurrent duplicates, in-progress requests, expired keys, another caller reusing the same key, and a process crash after the side effect but before the response is stored.