What is an idempotency key?
An idempotency key is a unique identifier a client sends with a request so the server can recognise a retry of the same request and return the original result instead of performing the action twice.
An idempotent API operation has the same effect whether it runs once or several times. Reading data is naturally idempotent; charging a card is not, unless the API is designed for it.
How idempotency keys work
The client generates a unique value, such as a random UUID, for each logical operation and sends it in an Idempotency-Key header. The server stores the key with the result of the first request. If the same key arrives again, the server returns the stored result instead of repeating the work. Keys are usually kept for a limited time, such as 24 hours.
An idempotency key example
A checkout sends “create payment” with a fresh key. The connection drops before the response arrives, so the client retries with the same key. Without idempotency, the customer is charged twice. With it, the server recognises the key, finds the completed payment and returns it.
Idempotency vs retry
Retries are how clients survive timeouts and network errors; idempotency is what makes retries safe. Retry only operations that are idempotent or carry an idempotency key, and back off exponentially so retries do not pile onto a service that is already struggling.
Last reviewed 2026-11-01.