Networks fail in the middle. A client sends a request, the server does the work, and the response is lost on its way back. From the client's side, there are two possibilities that look identical: the request never arrived, or it arrived and succeeded. The only safe move is to retry — and the only way retrying is safe is if the server can recognize it has seen this request before.
That recognition is what an idempotency key provides. This guide covers how it works, where it goes wrong, and a reference implementation you can adapt.
What idempotent actually means
An operation is idempotent if performing it several times has the same effect as performing it once. PUT /users/42 with the same body is idempotent. POST /charges is not — unless you make it so. An idempotency key is a client-chosen token, sent with the request, that lets the server collapse repeats into one.
The contract
Before writing any code, agree on the contract. Ours has four rules.
- The client generates a unique key per logical operation and reuses it on every retry.
- The server stores the key together with a fingerprint of the request and the eventual response.
- A repeat with the same key and the same fingerprint returns the stored response.
- A repeat with the same key but a different fingerprint is an error — it almost always signals a client bug.
A reference implementation
The tricky part is concurrency. Two retries can arrive at the same moment, before the first has finished. The key record has to act as a lock.
type Stored =
| { state: "in_progress"; fingerprint: string }
| { state: "done"; fingerprint: string; status: number; body: string };
export async function withIdempotency(
key: string,
req: Request,
handler: () => Promise<Response>,
): Promise<Response> {
const fingerprint = await hashRequest(req);
// Atomically claim the key. Only one caller can win this insert.
const claimed = await db.insertIfAbsent(key, { state: "in_progress", fingerprint });
if (!claimed) {
const existing = await db.get(key);
if (existing.fingerprint !== fingerprint) {
return json({ error: "idempotency_key_reused" }, 422);
}
if (existing.state === "in_progress") {
return json({ error: "request_in_progress" }, 409, { "Retry-After": "1" });
}
return new Response(existing.body, { status: existing.status });
}
const res = await handler();
await db.set(key, {
state: "done",
fingerprint,
status: res.status,
body: await res.clone().text(),
});
return res;
}Why claim first, work second
The insert-if-absent has to happen before the handler runs. If you check, then work, then write, two concurrent retries both pass the check and both do the work. That is the exact bug the key exists to prevent.
What to store, and for how long
- The key, scoped to the account or API credential. Never let one customer's key collide with another's.
- A request fingerprint — a hash of method, path and body.
- The response you returned, including status code and body.
- A timestamp, so you can expire the record.
We keep keys for 24 hours. That comfortably covers every retry policy we've seen in the wild, and it keeps the table small enough to stay fast.
Testing the hard cases
Happy-path tests prove very little here. The behaviors worth covering are the ugly ones:
- Two identical requests sent concurrently produce exactly one side effect.
- A request that crashes after claiming the key does not strand it forever — in-progress records need a timeout.
- The same key with a different body is rejected, not silently accepted.
- A response that was a failure is replayed as a failure, rather than retried — unless you've deliberately designed otherwise.
Get this one primitive right and a surprising amount of your reliability story gets simpler. Retries stop being scary, clients can be dumb, and the 3 a.m. question — did that go through? — finally has an answer.



