An Idempotency Key Promises One Execution, Not Eventual Success

Here is the design decision that tells you whether someone has actually thought about idempotency or is repeating a definition.

Stripe saves the status code and body of the first request made under a given idempotency key regardless of whether it succeeded or failed. If that first attempt returned a 500, every subsequent retry with the same key returns the same 500.^[1]

That sounds broken the first time you read it. It is correct, and the reason it is correct is the thing worth understanding: an idempotency key is a promise about how many times the operation executes. It is not a promise that the operation works.

Once you hold that distinction, the rest of the design falls out, and so do the four places homegrown implementations usually go wrong.

Why This Exists at All

A client sends a request to charge a card. The connection drops before a response arrives. The client now knows nothing useful: the request may have never landed, may have landed and failed, or may have succeeded with the response lost on the way back.

Its two options are both bad. Retry, and risk charging twice. Do not retry, and risk losing an order that the customer believes they placed. There is no third option available from the client alone, which is the point: this cannot be solved on the client, and no amount of careful timeout handling fixes it.

The idempotency key moves the decision to the server, which is the only party that knows what actually happened.

The Four Places It Goes Wrong

1. Generating a new key per attempt. The single most common error, and it silently removes all protection. The key identifies the logical operation: one attempt to charge one customer for one order. Generate it once, before the first send, and reuse it for every retry.^[1] A fresh UUID per attempt tells the server that each retry is a brand new charge, which is precisely the outcome you were defending against.

This means the key usually needs to be generated further up your stack than feels natural, and to survive a process restart if the retry might.

2. Not fingerprinting the parameters. If a client reuses a key but changes the payload, that is a bug in the client, not a retry. Stripe compares incoming parameters against the original and errors when they differ.^[1]Returning the cached response instead would silently discard the caller's new intent and make the bug invisible, possibly for months.

3. Treating concurrency as a lookup.The naive implementation reads the key, sees nothing, and proceeds. Two retries arriving simultaneously both read nothing and both proceed, which reproduces the double execution exactly. You need a lock or a unique constraint that makes the second one wait or fail, not a read followed by a write. Stripe's own account notes that a request conflicting with another executing concurrently does not get a saved result.^[1]

4. Storing keys forever. Idempotency is a bounded window, not a permanent ledger. Stripe prunes after at least 24 hours and treats a key reused after pruning as a new request.^[1] Twenty four hours covers real network failures and client retries; keeping keys indefinitely grows a table without bound to defend against a retry nobody is going to send.

What to Store, Precisely

Not a boolean. Storing “this key was used” means a retry gets no useful answer, and the client is back where it started.

Store the response: status code and body.^[1,2] A retry then receives byte-for-byte what the original caller would have received, which is what makes the retry genuinely transparent. The client does not need to know it was a replay.

And record it in the same transaction as the effect. If you charge the card and then crash before writing the key, the retry executes again and you have achieved nothing. If you write the key and then crash before charging, you have cached a success that never happened. This is the hard part of the implementation, and it is why the durable version lives in your database rather than in a cache, which is a different decision from ordinary caching despite looking similar.

Where It Is Heading

There is an IETF effort to standardise the header itself, so that Idempotency-Key means the same thing across APIs rather than being a per-vendor convention.^[3] Worth tracking, and worth using the same header name now even while it is a draft, because the cost of matching the emerging convention is zero and the cost of inventing your own is a permanent integration note.

The Coupling Worth Naming

This is the other half of an argument I made about rate limiting: telling a client to retry after a 429 is only safe advice if retrying is safe. A rate limiter that returns Retry-After on a mutating endpoint with no idempotency key is instructing clients to do something that can duplicate their data.

The two features get built by different people at different times, and nobody owns the interaction. Which is a good general description of how this class of bug happens: not from either component being wrong, but from the seam between two correct components going unexamined. The same shape shows up across service boundaries, and it is why broken authorization, another seam problem, tops the OWASP API list.

The same mechanism arrives from the other direction in messaging, where duplicates are not an edge case but the guarantee: exactly-once delivery does not exist, so the consumer has to be idempotent for the same reasons and with the same same-transaction requirement.