Product → API Products
Idempotency Key
A client-provided unique key that lets a server recognize repeated API requests as the same logical operation.
Where it fits
An idempotency key is a practical API pattern for making retries safe. It is common in payment APIs, order creation, job submission, and any endpoint where duplicate writes would be harmful.
Mental model
The client sends a unique key with a request. The server stores the result for that key. If the same key arrives again, the server returns the original result instead of executing the operation again.
Example
A client sends Idempotency-Key: order-123-create-attempt-1 when creating an order. If the network times out and the client retries with the same key, the server can avoid creating a second order.
Design details
Good implementations define key scope, expiration, request-body matching, storage durability, concurrency behavior, and response replay semantics.
Common mistakes
- Generating a new key for every retry.
- Storing keys too briefly for real client retry windows.
- Reusing one key for different logical operations.
Related concepts
API idempotency, retry, request-response, transactions, and distributed systems.