Why Retries Are Dangerous
Networks drop responses. A client sends a payment, the server commits it, but the acknowledgment is lost. The client retries, and without protection the payment runs twice. Idempotency makes a repeated request have the same effect as one request.
The Idempotency Key
- The client generates a unique idempotency key for the logical operation and sends it with every retry.
- The server stores processed keys, often in a table with a unique constraint.
- On the first request it does the work and records the key plus the result.
- On a retry it finds the key already present and returns the stored result without redoing the work.
Making It Atomic
The work and the key insertion must happen in the same transaction. If they split, a crash between them could record the key without the effect, or vice versa. A unique constraint on the key column lets the database reject a concurrent duplicate cleanly.
Beyond Payments
The same pattern protects queue consumers, webhook handlers, and any operation that may be delivered more than once under at least once semantics.
Key idea
Idempotent retries attach a unique key recorded in the same transaction as the effect, so a repeated request returns the prior result instead of duplicating work.