Idempotency Keys

The duplicate problem

Networks are unreliable, and that unreliability creates a specific, expensive trap. You send a POST to create something, the server receives and processes it perfectly well, but the response is lost somewhere on the way back to you. Your code, seeing no reply within its timeout, retries the request — and now you may have created the very same record twice without ever knowing.

For anything with a real side effect, such as a payment or a new case, that is a genuine and costly risk rather than a theoretical one. An idempotency key is the standard remedy. It is a unique value you attach to a request so the server can recognise a retry of the exact same operation and return the original result, instead of performing the work a second time and producing a duplicate.

How a key works

You generate one unique key per logical operation and send it with the request, usually in a dedicated header. The first time the server sees that key, it processes the request normally and stores the outcome against the key for a period. If the same key ever arrives again, the server skips reprocessing entirely and simply replays the stored response it produced the first time.

POST /v1/payments HTTP/1.1
Idempotency-Key: 7c1f9a2e-4b3d-4e88-9f10-2a6b5c8d1e34
Content-Type: application/json

The practical result is that retrying a create becomes completely safe. At most one record is ever produced, no matter how many times the request is sent or how the network misbehaves in between attempts, which is exactly the guarantee you want around money and other irreversible actions.

Generating good keys

A key must be unique to the operation, not to the individual attempt. A UUID generated once and then reused across every retry of the same logical action is the standard, well-trodden approach. The crucial discipline is to create the key before the first send and then hold onto it for all the retries that may follow.

Generating a fresh key on each attempt defeats the entire mechanism, because the server sees each try as a brand-new, unrelated operation and happily creates a duplicate for each one. Make your keys opaque and unpredictable, store them alongside the work you are doing if it spans processes or restarts, and let them expire after a sensible window so they do not accumulate without bound on either side.

When you need one

Idempotency keys matter for unsafe, non-idempotent operations — chiefly POST requests that create resources or trigger actions with side effects. Methods that are already idempotent by definition, such as GET, PUT, and DELETE, can be retried safely without a key, because repeating them does not change the final state of the resource.

Always check each endpoint's documentation, though, because the details vary: not every POST accepts a key, and the header name the API expects can differ from one service to the next. Where a key is offered, using it is almost always the right call for production traffic that you cannot afford to duplicate, even if failures feel rare in testing.

Putting it together

Combine idempotency keys with sensible retry logic to get the full benefit. Retry on network failures and on 5xx responses, reuse the same key throughout every attempt for a given operation, and back off between tries so you do not hammer a struggling server. Done well, transient failures become invisible to your users rather than dangerous to your data.

For the method semantics that underpin all of this — which verbs are safe, which are idempotent, and why that distinction governs when a key is needed — read HTTP methods explained, which is the natural companion to this topic.