Idempotency key
A client-supplied identifier that lets a request be retried safely without repeating its effect.
When a request times out you often cannot tell whether it succeeded. An idempotency key solves this: the client generates a unique key, the server stores the outcome against it, and a retry with the same key returns the stored result instead of acting again. It turns "did that go through?" from a guess into a question the server can answer.
Full guide:
How to make an API endpoint safe to retry
— Make the operation idempotent with a client-generated key. The client creates a unique key before its first attempt and sends it with every retry of that same logical operation. The server stores the outcome against the key and returns the stored result instead of acting again. This turns "did that go through?" from a guess into a question the server can answer.
Key facts
- The key must be generated by the client before the first attempt, because a key created per attempt makes every retry a new operation.
- The server stores the response against the key, so a retry returns the original outcome rather than a fresh one.
- Idempotency keys matter most on timeouts, where the client cannot tell success from failure — a plain retry may double-charge or double-create.
- Keys need an expiry: stored indefinitely they become an unbounded table, and reused too early they mask genuine new requests.
Frequently asked questions
Is a retry safe without an idempotency key?
Only for operations that are naturally idempotent — a GET, or a PUT that sets an absolute value. Anything that creates or increments needs a key, because a timeout gives you no way to know whether the first attempt landed.
What should the key be?
Anything unique to the logical operation and stable across retries — a UUID generated when the user clicks the button, not when the HTTP call is made. The distinction is the whole point.
Machine-readable copy of this page:
/glossary/idempotency-key.md