Skip to content
TheQuantaSpace
← Research
Systems1 min read

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

  1. Scope keys per account. Two customers must never collide on the same key.
  2. Lock while in flight. If a retry arrives while the first attempt is still running, return 409 rather than starting a second execution.
  3. Fingerprint the request. If the same key arrives with a different body, that’s a client bug. Reject it.
  4. 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