Idempotency
Also known as: idempotent operation, idempotency key
Idempotency is the property that performing an operation once and performing it many times produce the same end state. In distributed systems it is what makes retries safe: a client that never learns whether its request succeeded can send it again without double-charging, double-shipping, or double-writing.
Last reviewed · Part of the Architecture Glossary
In practice
The mechanism is an idempotency key: the client generates a UUID per logical intent (not per HTTP attempt) and sends it as a header. The server stores key → (status, response_body) in the same transaction that performs the write. A repeat of the same key returns the stored response instead of executing again.
POST /payments
Idempotency-Key: 7f3c1a90-... # generated once, reused on every retryThree details decide whether it actually works:
- Same transaction. If the key is recorded in Redis and the charge in Postgres, a crash between them gives you the double-charge you were trying to prevent.
- Concurrency. Two retries can arrive at once. A unique constraint on the key column turns the race into a duplicate-key error you can convert into "return the stored response."
- Expiry. Keys need a TTL — 24 hours is common — or the table grows forever. Any retry after the TTL is unprotected.
When it matters
Any endpoint reachable by a retrying client: payment capture, order placement, message consumers on an at-least-once queue, webhook receivers. PUT and DELETE are naturally idempotent; POST is not, and that is where the money is.
Common mistake
Generating the key inside the retry loop. If each attempt gets a fresh key, every attempt is a distinct operation and you have built an elaborate no-op. The key belongs to the user's intent, so mint it where the intent is formed — typically the client, on button press.
See also
- At-Least-Once DeliveryAt-least-once delivery guarantees a message reaches its consumer one or more times, never zero.
- Exactly-Once SemanticsExactly-once semantics means each message produces its effect precisely once.
- Transactional OutboxThe transactional outbox pattern writes an outgoing message into an `outbox` table inside the same database transaction as the state change it describes.