Glossary
Idempotency key
A unique value sent with a request so the server can recognize a retry and return the original result instead of doing the work twice.
In plain terms
When a request times out, you can’t tell whether the server did the work. Retrying is the obvious move, and it’s also how customers get charged twice.
An idempotency key fixes that. The client generates one value per intended action and sends it with every attempt. The server remembers the first result for that key and hands it back for any repeat, so the action happens once however many times it’s sent.
See what happens without it
The failure pattern this protects against, duplicate action after an ambiguous result, played out step by step.
Scroll the diagram sideways to see every system.
Ana is refunded twice, and every further retry would pay again.
What goes wrong:
- The agent asks the payments API to refund Ana $50.
- The money moves, but the reply is lost on the way back.
- Assuming the refund failed, the agent sends it again.
- Ana is refunded twice, and every further retry would pay again.
With the safeguard:
- Each refund carries a unique idempotency key.
- The reply is lost again.
- The retry reuses the same key, so the API recognises it and returns the first result.
- One refund, no matter how many retries.
When it mattered
Stripe’s payments API accepts an idempotency key on every state-changing request for exactly this reason: a client that retries after a network failure must never double-charge a customer.