Retries are necessary in distributed systems, but they can create duplicate work when a client cannot tell whether the server received a request. An idempotent API makes repeated requests produce the same intended result as one request. This approach helps clients recover from timeouts without charging a customer twice, creating duplicate records, or provisioning the same resource repeatedly.
Retries Expose Ambiguous Requests
A network failure does not always mean that an operation failed. The server may have completed the request just before the connection closed. If the client sends the request again, the server may process the same business action twice.
This problem is especially serious for operations that create or charge something. A request to create an order, issue a payment, send a message, or start a cloud resource can have an external effect that cannot be safely repeated. After a timeout, the client may not know whether it should retry, query the result, or report an error.
HTTP Methods Set Expectations
HTTP provides a starting point for deciding when a request can be repeated safely. GET, HEAD, OPTIONS, TRACE, PUT, and DELETE are defined as idempotent in RFC 9110. The standard defines idempotency by the intended effect on the server, not by whether every response is identical. For example, the first DELETE might return success while a later identical request returns not found, even though the resource remains deleted.
POST is not automatically idempotent because repeated requests can create multiple resources. That does not make POST unsuitable for retryable operations. It means the application must add a way to recognize when repeated requests represent the same client intent.
Idempotency Keys Protect POST
An idempotency key is a unique identifier attached to one logical operation. The client creates the key once and sends the same key when retrying that operation. The server stores the key with the operation result. When the same key arrives again, the server can avoid performing the side effect a second time and respond as though the earlier request had already been processed.
The key should represent one request, not one user or one endpoint. A new business action needs a new key. The server should also associate the key with the request parameters or a fingerprint of the payload. A reused key with different data may be rejected rather than silently treated as a new action. MDN's HTTP reference documents this pattern, including key expiration, payload mismatches, and conflicts while the first request is still running.
These rules belong in the API contract. It should state which endpoints accept or require keys, how long keys remain valid, what happens when a request is still processing, and whether the server returns a semantically equivalent response. Clear rules are more reliable than asking clients to guess whether a timeout is safe to retry.
Storage Must Be Atomic
The key must protect both the request record and the business change. Recording a key and then creating an order in separate operations can still produce duplicates. The service might save the key, fail before creating the order, and incorrectly treat a later retry as complete.
AWS describes this requirement in its guidance on making retries safe with idempotent APIs. The service should combine recording the request identity with the related mutations in an atomic, consistent, isolated, and durable operation. AWS also explains that this prevents the service from recording the token without creating the resource, or creating the resource without recording the token.
Idempotency does not remove the need for timeouts, backoff, validation, authentication, or monitoring. It gives those mechanisms a safer foundation. Teams should test lost responses, duplicate deliveries, concurrent requests with the same key, changed payloads, expired keys, and failures between each persistent state change. The goal is not merely to retry more often. It is to make the result of uncertainty predictable.
References
Fielding, R., Nottingham, M., & Reschke, J. (2022, June). HTTP semantics (RFC 9110). RFC Editor. https://www.rfc-editor.org/rfc/rfc9110.html
Featonby, M. (n.d.). Making retries safe with idempotent APIs. Amazon Web Services. https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
MDN Web Docs. (n.d.). Idempotency-Key header. Mozilla. https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Idempotency-Key