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 →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
An idempotent API makes repeated attempts at the same logical operation produce the same intended server-side effect as one attempt. That matters when a client times out or loses its connection: the server may have completed the request even though the client never received the response. For a mutating operation that is not naturally idempotent, a stable idempotency key can let the server recognize a retry and return the original outcome instead of performing the operation again.
Idempotency does not make delivery exactly once across a distributed system. It makes retries safe within a defined operation, scope, and retention period—and only if the server handles duplicate requests and their side effects correctly.
What is idempotency?
RFC 9110 defines an HTTP 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 important phrase is intended effect. A server may write a log entry or update a request timestamp on each attempt while preserving the same business outcome.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteFor example, setting an account’s notification preference to “off” has the same intended result whether the request is applied once or several times. Creating a new order is different: processing the same creation request twice could create two orders unless the application prevents it.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
Idempotency is about the effect of repeated attempts, not a guarantee that the network delivers a request once, that every internal step runs once, or that multiple services commit together.
Why retries can create duplicate operations
A timeout leaves the client uncertain. It may mean the request never reached the server, the server rejected it, or the server committed the change but the response was lost. If the client sends a new request to recover, the server can perform the same business operation twice.
This ambiguity appears in payment submissions, order creation, account provisioning, and queue consumers. A client or worker cannot infer from a missing response alone whether the original operation took effect. A retry is safe only when the operation’s semantics or the application’s duplicate-handling contract makes it safe.
HTTP method semantics and idempotency keys
HTTP method semantics provide repeat-safety for some requests. For other mutations, an application can add a key that identifies one logical operation across multiple transport attempts.
| Approach | How repeat-safety works | What to watch |
|---|---|---|
| HTTP method semantics | RFC 9110 identifies safe methods, PUT, and DELETE as idempotent. Repeating the same request is intended to have the same server effect. | The application must still implement the method consistently with its semantics. Internal logging or other incidental effects may occur more than once. |
| Application-level idempotency key | The client sends the same key for every retry of one logical mutation. The server associates that key with the operation and its outcome. | The API must define key scope, parameter matching, concurrent behavior, replay behavior, and retention. A new key on every retry defeats deduplication. |
Google Cloud’s HTTP API guidance says POST and PATCH are neither safe nor idempotent by default. That describes the methods’ general semantics; an API can still define and implement repeat-safe behavior for a particular operation. Conversely, choosing PUT or DELETE does not excuse an implementation that produces unintended duplicate business effects.
Rank #2
RFC 9110 says a client may retry an idempotent request after a communication failure before it reads a response. It also says, “A proxy MUST NOT automatically retry a request with a non-idempotent method,” except when the proxy knows the operation is idempotent or can determine that the original request was never applied.
How idempotency keys work
An idempotency key is a client-provided identifier for one intended operation, not for one network attempt. The client generates it once, keeps it stable while retrying that operation, and uses a different key for a genuinely new operation. The server uses the key—along with its defined scope—to find or claim the operation and to decide whether to execute, wait, reject, or replay.
Free tools Windows power users keep installed
One-click scans. No signup required.
1. Define what counts as the same operation
Decide what user intent the key identifies. For an order, it might represent one checkout submission; for a payment, one attempt to charge a specific transaction. A key that is too broad can merge separate actions, while a key that changes during retries cannot connect them.
Scope the key appropriately, such as to a customer or tenant and an operation type. The same string used by unrelated customers should not accidentally identify the same work.
2. Generate once and reuse on retries
The client should create a sufficiently unique key before its first attempt and persist it for as long as that logical operation may be retried. Stripe recommends a high-entropy value such as a UUID in its own API guidance. The exact header name, format, and length limit are provider-specific; an API should document its own requirements.
Do not generate a fresh key after a timeout just because the first response is missing. That would tell the server that the retry is a different operation.
3. Validate and claim the key atomically
Before applying the business mutation, the server should validate the request and atomically determine whether the key is new, already completed, or currently in progress. A lookup followed later by a separate insert is not enough: two simultaneous requests can both observe that no record exists and then both execute.
Use an atomic claim, a uniqueness constraint, or an equivalent transactional mechanism so concurrent requests for the same scoped key cannot both win. Store a request fingerprint or equivalent representation as well. If a client reuses a key with different parameters, the server should reject or otherwise explicitly handle the mismatch rather than silently treating the changed request as the original.
4. Coordinate the record with the business effect
Where possible, persist the idempotency state and the business mutation in the same database transaction. If the operation also triggers work in another service, a transactional outbox or durable workflow can connect the local commit to downstream delivery. These are design approaches, not a single architecture mandated by HTTP or by all provider APIs.
The key record must remain durable through the failures the API promises to handle. If the business change commits but the key record is lost, a retry may look new and execute the change again.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
5. Define behavior while work is in progress
Two identical requests may arrive before the first has finished. Choose a documented response: wait for the first operation, return an in-progress result, or return a retryable conflict. In every case, ensure the second request cannot independently apply the mutation. If the client receives an in-progress or retryable response, explain whether it should retry with the same key and when.
6. Save enough outcome to answer a retry
After completion, preserve the information the API needs to honor its contract. That may be the original HTTP status and response body, or an operation identifier and a way to retrieve its current state. A duplicate should communicate the result of the original logical operation rather than rerun its mutation.
For asynchronous work, returning the same operation reference is often clearer than pretending the work completed synchronously. The API can expose a status resource so the client can distinguish accepted, in-progress, completed, and failed work.
7. Set a retention horizon
Decide how long a key and its outcome remain available based on client retry limits, queue redelivery windows, and the time it can take to recover from an outage. Once a record expires, an old retry may be treated as new. State that boundary in the API contract and make the client’s retry behavior compatible with it.
Recommended Free Tools
What an API contract needs to specify
An idempotency key is useful only when both sides can rely on the same rules. Document the following behavior for each operation:
Best Value
- Scope: whether keys are unique per account, tenant, endpoint, operation type, or another boundary.
- Parameter matching: whether a repeated key must carry an identical body and which differences cause an error.
- Concurrent duplicates: whether a second request waits, receives an in-progress response, or gets a retryable conflict.
- Replay result: whether the server repeats the original status and body, returns an operation reference, or provides another defined result.
- Failure handling: which validation failures, execution failures, and conflicts are stored as outcomes, and which permit a later attempt to execute.
- Retention: how long the key remains valid and what happens after it expires.
- Downstream effects: how the operation coordinates notifications, messages, payment processing, or other work beyond the primary database.
Stripe as one provider-specific example
Stripe’s API reference documents one concrete contract for idempotency keys on POST requests. As described in the documentation checked on October 7, 2026, Stripe saves the first status code and response body once endpoint execution begins, then returns that saved result for later requests using the same key. This includes a saved 500 response.
Stripe also documents parameter comparison: reusing a key with different parameters produces an error. It does not save a result when validation fails or when a concurrent request conflict occurs before endpoint execution begins. Stripe says keys may be pruned once they are at least 24 hours old; a request using a key after it has been pruned may be treated as new. These details describe Stripe’s API, not a universal HTTP rule or a recommended retention period for every service.
Idempotency is not exactly-once delivery
Idempotency can make retries of a defined operation converge on one intended effect, but it does not by itself coordinate every service involved in a workflow. A database transaction can protect changes within that database; it cannot automatically make an external payment, message delivery, and local state update one indivisible action.
For external or asynchronous work, make each boundary safe too. A downstream consumer may need its own deduplication identifier; an outbox can ensure a committed business change is eventually published; a workflow may need recovery steps for partial completion. The design should say which operation is protected and what happens when a side effect succeeds but the caller or upstream service does not learn that it succeeded.
Failure cases to test
Exercise the failure windows your contract is meant to cover. Useful cases include:
- The server commits the business change, but the response is lost; the client retries with the same key.
- Two requests with the same key arrive simultaneously.
- The process restarts while a key is marked in progress.
- The idempotency store is unavailable or the key record cannot be written.
- The same key is reused with a changed body or different operation parameters.
- A retry arrives after the key’s retention period.
- A downstream message or side effect is redelivered after it has already been handled.
For each case, verify both the returned response and the business state. A server can return a plausible error while still creating a duplicate, or replay a response while losing the underlying operation record. Tests should establish that the promised contract survives concurrency, restart, and recovery—not merely that the happy path returns the expected status.
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.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
