Idempotency keys

The problem: the duplicate link

A developer's script calls Snip's API to create a short link for each of 10,000 products. One request reaches Snip, the link is created, and the response is lost to a network blip. The script times out and, following good practice from the last lesson, retries. Snip creates a second link for the same product.

For Snip that's untidy. For a payment API it's a customer charged twice. The client did the right thing; the API made the retry unsafe.

An operation is idempotent if doing it twice has the same effect as doing it once. Reading is idempotent. "Set the link's target to X" is idempotent. "Delete link x7Kp" is idempotent: it's gone either way. "Create a link" and "charge £20" are not: each call does it again. The fix is to give the server a way to recognise the retry.

Idempotency keys

The client generates a unique key for each logical operation (a random UUID is typical) and sends it with the request. Retries of the same operation send the same key:

POST /links
Idempotency-Key: 5f1c9a2e-7b41-4d0e-9a8f-0c3e6d2b1a77
{ "long_url": "https://shop.example/products/4471" }

The server remembers each key it has seen, with the response it gave:

Getting the details right

The idea is simple; the edge cases are where implementations go wrong:

• Record the key and the effect together. If the link is created but the key isn't recorded (or the reverse), a retry does the wrong thing. Write both in the same database transaction.
• Same key, different request. If a client reuses a key with a different body, it's a bug on their side. Store a fingerprint of the request with the key, and return an error rather than guessing.
• Two attempts at once. A fast retry can arrive while the first attempt is still running. The first attempt claims the key (a unique constraint does this), and the second gets a 409 "still in progress" and retries later.
• How long to remember. Keys only need to outlive the client's retries. A day is common; after that keys can be deleted.
• Scope keys to the caller. Two different accounts may pick the same key by chance. Store it per account.

A minimal table:

CREATE TABLE idempotency_keys (
  account_id    bigint      NOT NULL,
  key           text        NOT NULL,
  request_hash  bytea       NOT NULL,   -- reject reuse with a different body
  status        int,                    -- null while the first attempt is in progress
  response      jsonb,
  created_at    timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (account_id, key)
);

Other ways to be idempotent

Keys aren't the only tool. Often the cleanest fix is to change the operation itself:

• Let the client choose the ID. PUT /links/{id} with a client-generated ID: a retry writes the same row again.
• Unique constraints. If each product may have one link, a unique index on (account, product_id) turns a duplicate into a clean "already exists" answer.
• Set, don't add. "Set the count to 18,431" can be repeated; "add 1" can't. Queue consumers (07.03 Delivery guarantees and idempotent consumers) use the same idea, recording which messages or batches they've already applied.

Recap

Interview questions