Networks fail in an annoying way: the request is processed, but the response is lost. The client cannot tell the difference between "it did not happen" and "it happened and I did not hear back", so it does the only reasonable thing and retries.
If the operation was "charge the customer", that retry is a problem.
An idempotency key is how a client tells the server: this is the same operation as before, not a new one. The concept is simple. The implementation has more corners than it appears.
The contract
The client generates a unique key for each logical operation, not for each HTTP attempt, and sends it in a header on every retry of that operation.
The server promises that, for a given key, the effect happens at most once, and that every attempt receives the same response.
That second part is the one that gets forgotten. Returning a generic "already processed" error is not enough for a client that never saw the first response and still needs the id of the thing that was created.
What to store
A key alone is not enough. A useful record looks like this:
sql
CREATE TABLE idempotency_keys (
scope text NOT NULL, -- tenant or API client
key text NOT NULL,
fingerprint bytea NOT NULL, -- hash of method, path and body
status smallint NOT NULL DEFAULT 0, -- 0 started, 1 completed
response_code int,
response_body bytea,
created_at timestamptz NOT NULL DEFAULT now(),
locked_until timestamptz,
PRIMARY KEY (scope, key)
);
Three of those columns deserve a comment.
scope prevents one customer from replaying, or colliding with, another customer's key.
fingerprint detects misuse. If the same key arrives with a different body, that is a client bug, and the server should reject it with an error instead of silently returning the old response.
status distinguishes an operation that finished from one that is still running.
The race
Two requests with the same key can arrive at the same time. That is not an edge case, it is exactly what a client with an aggressive timeout does.
The primary key decides who wins:
sql
INSERT INTO idempotency_keys (scope, key, fingerprint, locked_until)
VALUES (@scope, @key, @fingerprint, now() + interval '30 seconds')
ON CONFLICT (scope, key) DO NOTHING;
If one row was inserted, this request owns the key and proceeds. If none was, somebody else got there first, and the handler reads the existing row:
completed with the same fingerprint: replay the stored response, byte for byte.
completed with a different fingerprint: return an error. This is key reuse.
started and not expired: return 409 Conflict, and let the client retry shortly.
When the first request dies
This is the case that tutorials skip. The process crashes after inserting the key and before completing it. The key is now stuck in started, and every retry gets a conflict forever.
There are two ways to handle it.
If the effect is in the same database, put the business change and the key's completion in one transaction. A crash then rolls back both, and the key disappears with the work. The retry starts clean.
If the effect is external, such as calling a payment provider, you cannot make that atomic. Use the locked_until lease: once it expires, a new attempt may take over the key. And pass a key derived from yours to the downstream provider, so the same logical operation stays idempotent end to end:
csharp
var downstreamKey = $"{scope}:{key}:capture";
await _payments.CaptureAsync(order.PaymentId, amount, idempotencyKey: downstreamKey, ct);
What to cache
Once execution has started, store the outcome, including failures. If a request failed with a 500 after a side effect, a retry that runs the logic again might repeat the side effect.
Requests rejected before execution began, for example by validation, should not consume the key, so the client can fix the payload and try again.
Keys also need a retention policy. Stripe, whose API popularized this pattern, prunes keys after 24 hours. Pick a window longer than any realistic client retry horizon, and shorter than your willingness to store response bodies.
Conclusion
An idempotency key looks like a header, but it is really a small state machine with three states, a lease, and a rule about what the response must be.
The design question is not "do we have a key". It is "what is the answer when the same key shows up again at every possible moment: before, during, after, and after a crash". If you can answer that for each, the pattern holds.
References
- Idempotent requests in the Stripe API documentation.
- The IETF draft The Idempotency-Key HTTP Header Field, from the HTTPAPI working group.