Idempotency in APIs
What Idempotent Means for API Requests
An idempotency API is one where sending the same request several times has the same effect as sending it once. An idempotency key is a unique value that a client attaches to a request so that the server can recognize a repeat of it and avoid performing the action twice.
The concept matters because networks fail in ways that leave the client unsure what happened. A request may be processed by the server while the response is lost, or the connection may time out before the server replies. The client cannot tell whether the action succeeded, so it retries. If the action is not idempotent, the retry can create a second order, a second payment or a second account.
Some HTTP methods are idempotent by design. GET, PUT and DELETE are defined that way in the HTTP specification, which means a repeated call should leave the server in the same state. The response may still differ, for example a second delete may report that the item no longer exists. Setting a field to a value is idempotent, because setting it twice gives the same result. Adding one more item to a list, which is what POST usually does, is not. The overview of methods is in HTTP methods.
Webhook senders face the same problem, which is why receivers should expect repeated deliveries. See webhooks for details.
How Idempotency Keys Prevent Duplicate Actions
For operations that are not idempotent by nature, such as creating a payment, many APIs accept an idempotency key, often sent in a header named Idempotency-Key. The client generates a unique value for each logical operation and sends it with the request.
The server stores the key together with the result of the first request. If the same key arrives again, the server returns the stored result instead of performing the action a second time. Good implementations also check that the repeated request has the same content as the original, and they reject a reused key that carries different data.
The key should identify the operation, not the attempt. A client that retries a failed payment should send the same key each time, while a genuinely new purchase needs a new key. Servers typically keep keys for a limited period, so retries must happen within that window.
A Duplicate Order After a Network Timeout
An online shop's app sends an order request. The server creates the order, but the response is lost on a weak mobile connection. The app shows an error, and the customer taps the order button again.
Because the app sent the same idempotency key with both attempts, the server recognizes the second request. It returns the original order number instead of creating another order. The customer is charged once, and the app shows the same confirmation it would have shown the first time.
Without the key, the customer would have two orders and two charges, and support staff would need to correct them by hand.
Frequently asked questions
Are all GET requests idempotent?
GET requests are expected to be safe and idempotent, meaning they should only read data and should not change the server's state. Repeating a GET may return different data if the underlying resource has changed in the meantime. Idempotency describes the effect of your own request on the server, not whether the response stays the same over time.
Do idempotency keys have to be unique for every request?
They must be unique for every separate operation, but retries of the same operation reuse the same key. A new order, transfer or account creation needs a new key. Reusing one key for different operations can cause the server to return the wrong result, which is why many APIs reject a key that is reused with different request content.