Recommended Free Tools
If an API request times out, the server may still have completed it. Retrying could therefore create a duplicate charge or resource—or it could simply confirm the same intended result. The difference is idempotency: repeating an operation has the same intended effect as applying it once, provided the API’s contract and implementation actually support that behavior.
What idempotent means
RFC 9110 defines an idempotent request method as one where multiple identical requests have the same intended effect on the server as a single request. The key phrase is intended effect: idempotency does not promise that every response is identical or that nothing else happens. A server can record a log entry each time and still apply the requested change only once in effect.
As an Amazon Associate I earn from qualifying purchases.
Consider a thermostat. Repeating “set the temperature to 20 degrees” leaves the setting at 20. Repeating “increase the temperature by 2 degrees” changes it again each time. For an API, replacing a resource with a specified representation is the kind of operation PUT is designed to express. Creating a new charge can be a new mutation each time unless the payment API recognizes a retry as the same logical operation.
Idempotent is not the same as safe or read-only
HTTP uses safe for methods whose requested semantics are essentially read-only. It uses idempotent for methods whose repeated requested effect is the same as one application. A method can be idempotent and still change server state.
#1 Best Overall
- Used Book in Good Condition
| HTTP methods | Standard semantics |
|---|---|
| GET, HEAD, OPTIONS, TRACE | Safe and idempotent |
| PUT, DELETE | Idempotent, but not safe |
| POST | Not designated idempotent by the standard |
“Safe” does not mean that no incidental effect can occur. A server may log a request; the HTTP standard also gives the example of a safe request that selects an advertisement and charges an advertising account. The distinction is about what the caller asked the method to do, not every implementation side effect. Likewise, deleting a resource may return a different response on a repeat even though the intended outcome—having that resource deleted—has not changed.
Do not infer an application’s full behavior from its verb alone. A particular POST operation may be documented by its service as idempotent, but that guarantee comes from the API’s contract and implementation, not from POST itself. RFC 9110 says a client should not automatically retry a non-idempotent request unless it knows the operation is idempotent or can determine that the original request was never applied; a proxy must not automatically retry a non-idempotent request.
Why a timeout makes retries uncertain
A timeout tells the client that it did not receive a response in time. It does not tell the client whether the server received or completed the request. The server may have completed a payment or created a resource and then lost the response on the way back. From the client’s perspective, the operation’s outcome is uncertain.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →That uncertainty is why retrying a non-idempotent operation can repeat its effect. A client that sends a request to create a charge, receives no response, and sends a fresh request may cause two charges if the service treats them as separate operations. By contrast, repeating an operation with idempotent semantics—or repeating the same logical operation under a correctly implemented idempotency key—can avoid applying the intended mutation twice.
A timeout, a server error, or the absence of a response is not proof that the original operation did nothing. Retry only when the operation’s semantics or the service’s documented contract makes that safe, or when you can reliably establish that the original attempt was not applied.
How an idempotency key identifies a retry
An idempotency key is a caller-provided identifier for one intended operation. The client generates it once and reuses it when retrying that same operation. The server uses the key to recognize the repeated request and, depending on its contract, return the original result rather than perform a new mutation.
- Create one key for the intended operation. Treat the key as an expression of intent, not merely as a hash of the request body. Two requests with identical parameters can still represent two legitimate actions—for example, a caller may intentionally request two identical resources.
- Reuse that key for retries of the same operation. Creating a fresh key for every attempt can make each retry look like a new instruction.
- Follow the API’s parameter and retention rules. A provider may reject a repeated key with different parameters, or stop recognizing it after a retention period.
- Confirm how in-progress and completed requests are handled. The server needs defined behavior for simultaneous requests using the same key and for failures partway through processing.
For example, Stripe’s API documentation says its idempotency layer stores the first request’s resulting status code and body for a key, including a 500 result, once endpoint execution begins. It compares repeat-request parameters with the original and returns an error if they differ. Validation failures and conflicts with another in-progress request do not save a result. Stripe says keys may be removed after they are at least 24 hours old; using a key after it has been pruned can create a new request. Stripe accepts keys on POST requests; its GET and DELETE requests are idempotent by definition in its API, so keys on those methods have no effect. These are Stripe-specific rules, not general HTTP behavior or a universal key-retention standard. See Stripe’s idempotent requests documentation.
What a correct implementation has to protect
Deduplication depends on coordinating the key’s state with the mutation. If a service records a key as complete before the mutation succeeds, a retry could be suppressed even though the work never happened. If the mutation succeeds but the key record is not saved, a retry could apply the change again.
A service therefore needs suitable state tracking and concurrency controls, and it must define how the key record and associated mutation stay consistent. AWS guidance recommends checking whether a token has already been used, storing the response for a new token, and returning the stored response for a repeat. In event-driven systems, it also recommends passing the token downstream and having consumers track tokens so duplicate messages can be ignored. See AWS Well-Architected Framework guidance on making mutating operations idempotent and the Amazon Builders’ Library discussion of safe retries.
A key at one boundary does not make an entire multi-service workflow happen exactly once. Downstream services and queue consumers need their own appropriate duplicate-handling contracts. Retries can also remain unsafe if workers race without coordination, a key expires before a delayed retry, or the caller mistakenly uses one key for two distinct intended actions.
How to retry without amplifying a failure
Even when an operation is idempotent, retrying indefinitely or immediately can worsen an outage. If many clients retry at the same time, their requests can add load to an already struggling service. Exponential backoff increases the wait between attempts; jitter adds randomness so clients are less likely to retry in lockstep. Stripe’s engineering discussion recommends both for robust retry behavior: Designing robust and predictable APIs with idempotency.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteChoose a retry limit or deadline that fits the system’s needs. There is no single retry schedule established for every API, and backoff only paces requests—it does not make an operation idempotent or repair an incorrect deduplication implementation.
Quick Recap
A practical retry decision
- First, identify the operation’s intended effect. Does repeating the same request leave that effect unchanged, or can it create another resource, payment, or other mutation?
- Check the actual API contract. Confirm whether the endpoint is idempotent, whether it supports keys, how key reuse and parameter matching work, and how long a key remains valid.
- For a retry of the same logical operation, reuse the same key. Do not send a new key just because the first attempt timed out.
- Account for concurrent and downstream work. Verify how duplicate requests are coordinated and whether later services or consumers also suppress duplicate effects.
- Set a bounded retry policy. Use a limit or deadline with exponential backoff and jitter where appropriate; do not assume retries can continue without cost.
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.
