A card payment request times out after 50 milliseconds, and the client cannot tell whether the charge went through. This post replays that moment on a small local server, first without a key and then with one, and sets the result against what the IETF HTTPAPI draft and Stripe's API docs say a server should do. Both were read on 12 November 2026.
Receipt 1: the order sent twice
A POST creates something, so repeating it can create it twice. RFC 9110 lists OPTIONS, HEAD, GET, PUT and DELETE as idempotent and POST and PATCH as not. The draft puts the problem this way: a client sends a POST, the request times out, and the client does not know whether the resource was created or whether it can safely retry.
I wrote a 40-line Node server with a charge endpoint that takes 200 ms to answer, and a client that gives up after 50 ms. Run with no key, the client retries and the server sees two orders:
- t+0 POST /charges amount 4900, client gives up at 50 ms (TimeoutError)
- t+50 client retries the same POST
- t+250 server answers 201 ch_2 for the retry
- t+250 charges stored: 2, both for 4900
The first request was never cancelled on the server. Closing the connection on the client does not stop work already started.
Receipt 2: the same order with a key
The fix is a value the client invents once per logical operation and sends with every attempt. The server remembers the first outcome under that value. The header is Idempotency-Key, and the draft says its value is a string, with a UUID or similar random identifier recommended. Same run, same server, one UUID reused:
- send POST amount 4900 with the key, still running
- +50 ms retry with the key: 409 original still processing
- +250 ms first request finishes: 201 ch_1
- later retry with the key: 201 ch_1 again, same body, no new charge
- later same key, amount 9900: 422 key reused with a different body
- total charges stored: 1
The core of the server is a map from key to a fingerprint of the body and the saved result. This is the whole rule:
const prev = seen.get(key)
if (prev) {
if (prev.fp !== sha256(rawBody)) return send(422, 'different body')
if (prev.state === 'running') return send(409, 'still processing')
return send(prev.status, prev.body) // replay the saved answer
}
seen.set(key, { fp: sha256(rawBody), state: 'running' })
// ...do the work once, then save status and body under the key
It keeps state in memory, so it is a teaching model. A real one writes the key in the same transaction as the work, and checks two requests with one key cannot both pass the first line.
Line items: what the draft asks of a server
The draft is a working group document that is not yet an RFC, so details can still change. As of the repository text read today, it says:
- First requestProcess normally
- Retry after it finishedRespond as if completed, same intent
- Retry while running409 Conflict
- Key reused, other payload422
- Key required but missing400
It also lets a server compare a fingerprint of the payload (a checksum of the whole body or of chosen fields), requires a resource to publish its expiry policy, and lets a resource require keys that expire. A 409 needs no correction: the client waits and retries. For the other errors the client must fix the request first.
Line items: what Stripe does today
Stripe's docs describe one production design in detail. For API v1:
- Which requestsAll POST. GET and DELETE ignore keys
- Key lengthUp to 255 characters
- Suggested valueV4 UUID or random string
- SavedStatus code and body of the first request, 500s included
- RetentionKeys may be removed after 24 hours
- Changed parametersError, parameters are compared
- Failed validationNot saved, safe to retry
API v2 works differently: retries do not repeat successful operations, and failed or partly failed work is retried to completion where possible. Read the page for the version you use.
Staff notes: four mistakes with keys
A new key per attempt
Then every retry is a new order. Generate the key once when the user clicks, store it with the pending action, and reuse it for each attempt of that action.
A key built from personal data
Stripe advises against email addresses or personal identifiers as keys. Use a random value.
One key for two different bodies
The draft says a key must not be reused with another payload. A changed cart is a new operation and needs a new key.
Forgetting that keys expire
After the retention window a retry looks new. Retry inside the window, and tell clients what it is.
Questions at the till
Does a key make PUT or DELETE safer?
No need. Those methods are idempotent by definition in RFC 9110, and Stripe says its GET and DELETE ignore the header.
Why save a 500 error under the key?
Stripe v1 returns the saved response for a retry, even when it was a 500, so a retry cannot cause a second attempt of something that may have half run.
Is this the same as a rate-limit retry?
No. A 429 says wait and send again because nothing ran. A timeout says nothing about whether it ran, which is the case a key solves.
Receipt sources
- The Idempotency-Key HTTP Header Field, IETF HTTPAPI working group draft (repository text, last commit 22 October 2026)
- Stripe API reference, Idempotent requests
- RFC 9110, HTTP Semantics, idempotent methods
- The two runs above: a local Node server and client written for this post, run on 12 November 2026.



