Idempotency keys, in practice

Everyone agrees idempotency keys are good. Fewer people talk about what happens on day two.

Store the response, not just the key

If you only store the key, a retry gets a 409 and the client has no idea whether the first request succeeded.

create table idempotency (
  key text primary key,
  response jsonb,
  created_at timestamptz default now()
);

Scope keys to the caller

Two clients will eventually pick the same UUID generator seed. Scope by account.

Expire them

Twenty-four hours is plenty for most retry policies.