A client timeout does not tell you whether the server completed the request. The server may have created the resource or charged the payment, while its response was lost on the way back. If the client blindly sends the operation again, the effect can happen twice. Idempotency gives repeated requests the same intended effect as one request, making retries safer without promising that every distributed side effect happens exactly once.
Why a timeout can lead to a duplicate operation
Consider a client sending a request to create an order. The server processes it and sends a response, but the connection drops before the client receives that response. From the client’s perspective, the outcome is unknown: the operation may have failed, or it may have succeeded and only the response was lost.
As an Amazon Associate I earn from qualifying purchases.
Retrying a non-idempotent operation without protection can create a second order or repeat another action. The core design problem is therefore not simply “Should the client retry?” It is whether repeating the request preserves the operation’s intended effect.
What idempotency means in HTTP
RFC 9110 defines a method as idempotent when “the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.” The definition is about the requested effect, not every incidental event: logging each request, for example, may happen more than once. RFC 9110, Section 9.2.2, published by the IETF/RFC Editor in June 2022, identifies PUT, DELETE, and safe methods as idempotent.
#1 Best Overall
This matters when a connection fails before the client can read the response. Because repeating an idempotent request has the same intended effect, a client can retry even when it cannot tell whether the first attempt was applied. By contrast, RFC 9110 says a client should not automatically retry a non-idempotent request unless it knows the request semantics are safe to repeat or can determine that the original request was never applied.
HTTP method semantics and idempotency keys solve related problems differently
| Approach | What makes a retry safe | Example and scope |
|---|---|---|
| HTTP-native semantics | The method’s intended effect is unchanged by multiple identical requests. | RFC 9110 defines PUT, DELETE, and safe methods as idempotent. This is a method-semantic rule, not a key-based protocol. |
| Application-level idempotency key | The application associates a stable key with a logical operation and its result, then recognizes retries using that same key. | Stripe documents this for POST requests. Its behavior is specific to Stripe, not a universal HTTP rule. |
These approaches are not competing standards. An API can define an operation as safe to repeat even when it uses POST; RFC 9110 allows a client to repeat a POST when it knows through the resource’s design or configuration that doing so is safe. A key is one application-level way to make selected mutating operations retryable without changing their HTTP method.
How an idempotency key works in practice
The client creates a key for one logical operation and sends it with the request. If it retries that same operation because the response was uncertain, it reuses the key. The server can use the key to find the operation’s recorded outcome instead of carrying out the same operation again. A genuinely new operation needs a new key.
Free tools Windows power users keep installed
One-click scans. No signup required.
Stripe’s documentation provides a concrete, vendor-specific example. Stripe accepts idempotency keys on POST requests, compares parameters when a key is reused, and errors if the parameters differ. Once endpoint execution begins, Stripe saves the first result and returns that result for later requests with the same key, including when the saved result is a 500 error. Stripe says it does not save a result when parameter validation fails or when a concurrent request conflict prevents endpoint execution from beginning. Stripe’s idempotent requests documentation also describes V4 UUIDs or another sufficiently random string as key choices, sets a 255-character maximum, and says keys may be pruned after they are at least 24 hours old. After pruning, reusing a key can start a new request. These are Stripe’s documented rules, not requirements for every API.
Designing a retry flow around keys
- Define the logical operation. Decide which action must not be duplicated, such as one payment attempt or one resource-creation request.
- Create one stable key for that operation. Keep it unchanged across retries after a timeout, dropped connection, or otherwise uncertain response. Mint a different key when the user or system initiates a genuinely new operation.
- Bind the key to the request content. Specify what happens if a caller reuses a key with different parameters. Stripe, for example, rejects a parameter mismatch rather than treating it as the same operation.
- Document what the server records and replays. Be explicit about when execution starts, which results are retained, what response a retry receives, how concurrent requests are handled, and how long keys remain usable.
- Test uncertain outcomes. Exercise cases where processing succeeds but the response is lost, where a retry arrives while the first request is still running, and where the same key is sent with changed parameters. The expected behavior should follow your API’s documented contract.
What idempotency does not guarantee
Idempotency is not a universal exactly-once delivery mechanism. RFC 9110 defines sameness in terms of the intended server effect and permits incidental per-request effects. Stripe’s documented persistence also applies only after endpoint execution begins; it does not claim that a key automatically coordinates arbitrary external side effects or multi-service workflows.
If an operation crosses service boundaries or triggers external systems, the API must define how those effects are coordinated and recovered. An idempotency key can help a service recognize a repeated logical request, but the cited HTTP standard and Stripe documentation do not establish a universal guarantee for every downstream action.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
