Make a retry of one logical mutation reuse the same idempotency key and the same request parameters. The server must implement a documented deduplication contract for that key; the key alone does not prevent duplicate work. This matters most when a request times out or the connection drops: the server may have applied the operation even though the client never received its response.
Why a timeout does not tell you whether a request succeeded
A client can lose its connection after a server has completed an operation but before the response reaches the client. From the client’s perspective, the result is unknown—not necessarily unsuccessful. Retrying a mutation as a new operation can therefore create a duplicate charge, order, or resource.
As an Amazon Associate I earn from qualifying purchases.
HTTP method semantics provide one baseline. RFC 9110 defines an idempotent method by its intended effect: repeating the same request has the same intended effect as sending it once. A server may still perform incidental work, such as logging each request, and the response to a repeated request need not be identical. RFC 9110 says a client may retry an idempotent request after a communication failure because its intended effect remains unchanged. RFC 9110, section 9.2.2, published by the IETF in June 2022, states that a client SHOULD NOT automatically retry a non-idempotent request unless it can know the semantics are idempotent or detect that the original was never applied.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsHTTP idempotency is not the same as safety
Safety describes whether a method is intended to change server state; idempotency describes the effect of repeating it. RFC 9110 classifies GET, HEAD, OPTIONS, and TRACE as safe. Safe methods, along with PUT and DELETE, are idempotent under the standard. POST is not generally guaranteed to be idempotent by its method definition, although an API may define idempotent behavior for a particular POST operation.
#1 Best Overall
| Method group | RFC 9110 property | Retry implication |
|---|---|---|
| GET, HEAD, OPTIONS, TRACE | Safe and idempotent | Repeating the request has the same intended effect; the response may differ. |
| PUT and DELETE | Idempotent, not classified as safe | Repeating the request has the same intended effect, even if a response differs. |
| POST | Not generally idempotent by method definition | Do not automatically retry unless the operation has an idempotency mechanism or you can establish the original was not applied. |
RFC 9110 also advises clients not to automatically retry a failed automatic retry. This is standards guidance, not a universal provider retry policy; follow the service’s documented behavior and keep automatic attempts bounded.
What an idempotency key does
An idempotency key is an API-specific identifier attached to one logical mutation. The client creates it before the first attempt. If the outcome is unclear, it resends the same operation with the same key and semantically identical parameters. An API that supports the mechanism recognizes the key and applies its documented duplicate-request policy instead of treating the retry as a new operation.
Rank #2
- Used Book in Good Condition
There is no shared HTTP-wide idempotency-key contract. The API defines how the key is supplied, what it identifies, whether simultaneous requests are coordinated, which results are saved, what duplicates receive, and how long the record lasts. Do not infer exactly-once execution from the presence of a key; describe the actual API guarantee, such as deduplicated effects or replay of a saved response.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Client implementation: keep one key with one operation
- Create the key when the logical operation is created. Generate it before the first network attempt, using the API’s documented format. Stripe recommends a UUID v4 or another sufficiently random string.
- Retain the key with the operation. If the client can restart before learning the outcome, persist the key and the corresponding request data so recovery uses the same identity.
- Reuse it only for retries of that operation. Keep the parameters semantically identical. Do not generate a replacement key just because a request timed out.
- Use a new key for a new user action. Even if its payload happens to match an earlier request, a separate logical operation needs a separate key.
- Follow the provider’s exact contract. Check the header or parameter name, syntax and length limits, case sensitivity, scope, retention, supported operations, mismatch response, and duplicate behavior in the endpoint’s current documentation.
- Handle mismatches as errors in operation identity or client state. Do not quietly change the payload while keeping the old key; correct the underlying issue or create a new logical operation with a new key.
Provider contracts differ
The examples below show why “supports idempotency keys” is not a complete implementation specification. These behaviors are provider-specific and should be checked against the current endpoint documentation.
| API contract | Documented behavior | Implementation consequence |
|---|---|---|
| Stripe | Stripe’s idempotent requests reference says it saves the first request’s status code and body for a key, including a 500, and returns that result on later uses. Results are saved only after endpoint execution begins; validation failures and conflicts with an already executing request are not saved as idempotent results. Parameters are compared, and mismatched reuse errors. The reference permits keys up to 255 characters and says keys may be pruned once they are at least 24 hours old; reuse after pruning starts a new request. | Do not assume a 500 retry will execute again: a saved result may be replayed. A key is not a substitute for correcting validation errors, and reuse after pruning may no longer deduplicate. |
| Amazon ECS | ECS documentation describes client-token idempotency for selected actions. A successfully completed request repeated with the same token and parameters returns the original result without further action. For RunTask, changed parameters can produce a ConflictException. Tokens are case-sensitive and should not be reused for another request. | Confirm the action is supported and preserve both token casing and parameters when retrying. |
| Amazon EC2 | EC2 documentation describes regional and zonal scopes for selected operations. The same token can identify separate operations across regions; with zonal scope, availability zone also matters. Relevant parameter changes can return IdempotentParameterMismatch. | Do not assume a token is globally unique across services, regions, or resources; understand the operation’s documented scope. |
Choose retry eligibility and pacing separately
An idempotency key answers how the API treats a repeated operation; it does not decide whether another attempt is appropriate. Use the provider’s status-code guidance, respect rate limits, and constrain automatic retries. Stripe’s error guidance recommends exponential backoff for HTTP 429 Too Many Requests. That advice is specific to Stripe’s guidance and does not establish a universal retry rule for every status or provider.
- Retry only failures the API or client policy identifies as retryable.
- Use bounded attempts or another explicit limit, and avoid an automatic retry loop.
- Apply the service’s pacing advice, especially for rate limits.
- When the outcome remains uncertain, retry the same operation with its original key rather than treating uncertainty as proof of failure.
Designing an idempotency contract for your API
For API designers, a key is useful only if the contract and implementation make duplicate behavior predictable. Specify the following for each supported operation:
- How the client supplies the key, including syntax, length, and case handling.
- Its scope: for example, per account, operation, endpoint, region, or availability zone.
- What makes requests equivalent and how a parameter mismatch is reported.
- How concurrent requests with the same key behave while the first is in flight.
- Which success and error outcomes are recorded, and which failures are not.
- Whether a duplicate replays a saved response, returns another defined result, or follows a different policy.
- How long records remain valid and what happens after expiry or pruning.
- Which methods and endpoints support the mechanism and which failures clients may retry.
The implementation also needs consistency between the operation and its deduplication record. Avoid a design in which the operation completes but its key/result is not recorded, or a concurrent duplicate executes while the first request is still in flight. The right storage and atomicity strategy depends on the system and any external side effects; HTTP semantics do not supply those guarantees. Stripe’s distinction between endpoint execution, validation failure, and an in-flight conflict illustrates why the contract must say which outcomes are saved. AWS Cloud Control API documentation describes a 36-hour token validity period, while Stripe documents a different pruning policy; neither duration should be generalized to other APIs.
Quick Recap
Best Value
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.
