Idempotency Keys
You'll learn to
- -Explain the timeout problem: the request may have succeeded even though the client never heard back
- -Make a POST safe to retry with an Idempotency-Key, and watch a retry return the original answer
- -Handle a reused key with a different body (409), and keep keys for a bounded time
GET, PUT and DELETE are idempotent by the HTTP rules: doing them twice is the same as once. POST is not, and that becomes a real production problem the moment a network timeout happens. The client never received a response, but the request may well have succeeded on the server. Should it retry and risk creating the thing, or charging the payment, twice?
An Analogy: Pressing the Elevator Button Again
You press the call button, nothing lights up, so you press it again. A sensible elevator system does not send two elevators. It recognizes it is the same call. An idempotency key is how a payment API recognizes "this is the same request again", not "someone wants to pay twice".
The Idempotency-Key Header
POST /payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{"amount": 4999, "currency": "usd", "customer_id": 42}
HTTP/1.1 201 Created
{"id": "pay_501", "status": "succeeded"}
# The exact same request, retried after a timeout - same key, same body:
POST /payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{"amount": 4999, "currency": "usd", "customer_id": 42}
# Server recognizes the key was already processed - returns the ORIGINAL
# result again, without charging a second time:
HTTP/1.1 201 Created
{"id": "pay_501", "status": "succeeded"}The client generates a unique key, usually a UUID (a long random-looking identifier), once per logical operation, before the first attempt. It sends the same key on every retry of that same operation. The server stores a mapping from key to the result it already produced. A retry with a key it has seen gets the stored result back, without running the action again.
The demo plays the whole story. The first attempt succeeds, but the reply is lost. The client retries with the same key and gets the same answer, and the money moves once. Then the same key arrives with a different amount, and a brand new key arrives for a genuinely new payment.
What Happens on a Body Mismatch
POST /payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{"amount": 9999, "currency": "usd", "customer_id": 42}
HTTP/1.1 409 Conflict
{"error": "Idempotency-Key already used with a different request body"}A key that shows up again with a genuinely different body is not a legitimate retry. It is either a client bug, such as accidentally reusing a key, or an attempt to piggyback a different operation on a used key. Returning 409 surfaces the mismatch. Silently processing the new body, or silently returning the old result, would hide a real bug.
A Reasonable Retention Window, Not Forever
Keys do not need to be stored forever. A retry that matters happens within seconds or minutes of the original, not months later. A bounded window, commonly 24 hours, covers realistic retries without an ever-growing key table.
This is the same pattern as the idempotency key in the database money chapter. Here it is the API-facing half of the same problem: stopping a network-level retry from becoming a duplicate business operation.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design Idempotency Shield in the API Design Lab's Production Patterns act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!