Idempotency keys: the API feature you'll wish you'd shipped on day one
Networks fail in the worst possible place, after the server did the work but before the client heard back. Idempotency keys turn "did my payment go through?" into a non-question.
A client sends POST /charges. The server charges the card, then the connection drops before the response
arrives. The client retries. Did the customer just pay twice?
Without help from the API, the client cannot know. Retrying is unsafe, and not retrying might lose the request.
The pattern
The client generates a unique key per logical operation and sends it with every attempt:
POST /v1/charges
Idempotency-Key: 6f1c2a8e-3b7d-4e0a-9c55-1d2e3f4a5b6c
Content-Type: application/json
{ "amount": 4900, "currency": "usd" }
The server stores (key → response) the first time it completes the operation. Any retry with the same key
returns the stored response instead of doing the work again.
The details that matter
- Scope keys per account. Two customers must never collide on the same key.
- Lock while in flight. If a retry arrives while the first attempt is still running, return
409rather than starting a second execution. - Fingerprint the request. If the same key arrives with a different body, that’s a client bug. Reject it.
- Expire keys. 24 hours is a common window; long enough for retries, short enough to bound storage.
CREATE TABLE idempotency_keys (
account_id uuid NOT NULL,
key text NOT NULL,
request_hash bytea NOT NULL,
status text NOT NULL, -- 'in_progress' | 'done'
response jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (account_id, key)
);
Retrofitting this later means auditing every mutating endpoint. Adding it to the first one costs an afternoon.
- #api
- #distributed-systems
- #reliability