· 2 min read
Idempotency keys, explained
Why a payments API needs them, the three cases a key has to handle, and the table that makes retries safe.
At Brightpay I spent a good part of four years on one question: what happens when a client sends the same payment twice? This post is the answer I wish I had on day one.
The problem is the timeout#
A client sends POST /charges. The API charges the card, writes the result, and sends the response. The response never arrives: a phone loses signal, a proxy times out. From the client's side, nothing happened. So it retries.
Without protection, the retry charges the card again. Telling clients not to retry does not work, because retrying is the right thing to do when you do not know if a request succeeded.

The key#
The client makes up a random key per operation, not per request, and sends it with every attempt:
POST /charges
Idempotency-Key: 7f3a9c2e-1b4d-4e8a-9f0c-2d6b8a1e5f37
The server stores the key with the response. When the same key arrives again, it returns the stored response and does nothing else.
Three cases#
That sounds like a cache, but a key has to handle three situations, and the third is where bugs live:
- New key. Insert it, do the work, store the response.
- Finished key. Return the stored response, byte for byte.
- Key in progress. The first attempt is still running. Return
409 Conflictand let the client retry later. Do not wait, and do not start the work again.
The table that handles all three:
create table idempotency_keys (
key text primary key,
account_id bigint not null,
request_hash bytea not null,
status text not null check (status in ('started', 'finished')),
response jsonb,
created_at timestamptz not null default now()
);
The insert in case 1 is insert ... on conflict do nothing. If it inserted a row, this request owns the key. If it did not, read the row and you are in case 2 or 3. The primary key does the locking for you.
Check the request too
Store a hash of the request body. If a key comes back with a different body, return 422. It is a client bug, and returning the old response would hide it.
The part outside the database#
The charge itself goes to a card network, which is not in your transaction. If the process dies after the charge but before storing the response, the key is stuck in started.
We fixed that with an outbox: the API writes the intent to charge in the same transaction as the key, and a separate relay talks to the card network and records the result. That pattern became Outboxer, a small Go library I still maintain.
Results#
Over the three years after we shipped keys, the API handled a few billion requests and produced zero double charges that we could trace to retries. Support went from weekly double-charge tickets to none. The keys cost one table and about two hundred lines of code.
Where I use this
Related posts

· 2 min read
Weighted routing at the load balancer, two metrics and a ten-minute timer. A canary setup small enough to explain on a whiteboard.
