What is the Idempotency-Key HTTP header pattern used by payment and other write APIs, who generates the key, and which requests should carry one?

## The problem it solves HTTP gives PUT and DELETE idempotency, so a client library may safely re-send them when a response is lost. POST has no such guarantee, and POST is what you use for "charge this card" or "place this order". When the connection drops with no response, the client faces an ambiguity it cannot resolve: the request may never have arrived, or it may have been fully processed with only the response lost. Retrying risks a double charge; not retrying risks a payment the customer thinks failed but which actually went through. HTTP itself offers no mechanism to resolve this. The `Idempotency-Key` header is the industry's application-level answer — popularised by Stripe and other payment APIs, and now the subject of an IETF draft (`Idempotency-Key` header field). It gives the server a way to recognize "this is the same logical operation I already handled". ## How it works, end to end 1. The client decides to perform an operation (charge $20). Before sending anything, it **generates a unique key** — a UUIDv4 is the standard choice — and persists it alongside its intent if the operation matters enough to survive a client restart. 2. It sends `POST /payments` with `Idempotency-Key: 8f14e45f-…` and the request body. 3. The server looks up the key within its scope. Not found → it executes the operation, stores the key together with the resulting status, headers and body, and responds normally (say 201 Created). 4. The response is lost. The client retries **the identical request with the identical key**. 5. The server finds the key, does **not** execute again, and returns the stored response: same 201, same payment id. The client ends up with the original outcome. Exactly one payment exists. ## Who generates the key, and why it must be the client Only the client knows that its second attempt is a retry of the first, rather than a genuinely new operation. If the server generated keys, every request would get a fresh one and nothing would ever deduplicate. So the key is client-supplied and its lifetime is tied to the client's *intent*, not to the request. This has a practical consequence people get wrong: the key must be generated **before** the first attempt and reused across all retries of that intent, including retries after a process restart. If your retry loop generates a new UUID each pass, you have built an elaborate way of doing nothing. Conversely, a client that reuses one key for two genuinely different operations will silently get the first operation's response back for the second — so keys must never be derived from something non-unique like a user id or a timestamp with second resolution. A good key is: unique per operation, opaque, unguessable enough that another tenant can't collide with it, and long-lived enough to survive the client's retry window. UUIDv4 satisfies all of that. Some clients derive it deterministically from the operation's own natural identity (order id + attempt intent), which is fine as long as the derivation is genuinely unique per intended effect. ## Where it belongs and where it doesn't **Use it on non-idempotent state-changing requests**: `POST /payments`, `POST /orders`, `POST /transfers`, and non-idempotent `PATCH` operations such as balance adjustments. **Don't bother on**: GET and HEAD (safe — nothing to deduplicate); PUT and DELETE (already idempotent by method, since re-sending the same replacement or removal converges). Adding keys everywhere just adds storage and confusion. **Send it as a header, not a body field.** A header is visible to gateways, proxies, logging and routing layers, it is method- and content-type-agnostic, and it keeps deduplication independent of your payload schema. It also means an SDK can attach it automatically to every mutating request without understanding the body. ## What the pattern does not do It is not distributed transactions, and it is not a general concurrency-control mechanism — it doesn't stop two *different* clients writing conflicting updates (that is what ETag preconditions are for). It only collapses repeats of the *same* logical operation. It is also not free: the server must maintain a durable dedupe store, decide the key's scope, decide how long keys live, handle two retries arriving concurrently, and decide what to do when the same key arrives with a different payload. Those are the follow-up questions that separate a candidate who has read about the header from one who has implemented it. ## The one-line version The client names the operation with a unique key; the server promises that a key is executed at most once and that later arrivals get the original answer back. That turns an unsafe POST retry into a safe one.