Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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

A request can succeed on the server even if a timeout or dropped connection keeps its response from reaching the client. Retrying it blindly may repeat the operation. Idempotency is the property that makes repeating a request preserve the same intended effect; an idempotency key is one application-level way to make selected operations safe to retry.

Why a timeout leaves the client uncertain

Suppose a client sends a request to create a resource or charge a payment, then times out before receiving a response. The timeout says the client did not get an answer; it does not prove the server failed to act. The server may have completed the operation and lost only the response on its way back.

If the client sends the operation again without a way to recognize the original attempt, the server may perform the effect twice. Idempotency addresses this ambiguity by making repeated identical requests have the same intended effect as one request, or by allowing the server to recognize and replay the result associated with the original logical operation.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

What HTTP idempotency means

RFC 9110, Section 9.2.2, defines an idempotent method by its intended server effect: “A request method is considered ‘idempotent’ if 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 consequence of handling a request; incidental effects such as logging may still differ. RFC 9110, Section 9.2.2

Methods the standard identifies as idempotent

RFC 9110 identifies PUT, DELETE, and safe methods as idempotent. For example, repeating a PUT that sets a resource to a particular representation should leave the resource in the same intended state as applying that request once. A DELETE can likewise be repeated without changing the intended result that the resource is absent. Safe methods are idempotent under the standard’s definition.

Why this matters for retries

When a connection fails before the client reads the response, the client may not know whether the first request took effect. RFC 9110 explains that a client can retry an idempotent request in that situation. For a non-idempotent request, a client should not automatically retry unless it knows the request semantics are safe to repeat or can determine that the original request was never applied. The key distinction is the operation’s semantics, not merely whether a response was received.

HTTP method semantics and idempotency keys solve different parts of the problem

HTTP defines method semantics; an idempotency key is an application-level mechanism that can make a selected operation safe to retry. They are not competing standards. An API can define an operation as idempotent regardless of its method name. RFC 9110 explicitly allows a POST to be repeated when the client knows, through the resource’s design or configuration, that repeating it is safe.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Approach What makes repetition safe Retry behavior after an uncertain response
HTTP-native semantics The operation’s intended effect is unchanged by multiple identical requests. RFC 9110 names PUT, DELETE, and safe methods as idempotent. A client can retry an idempotent request even when the original may have succeeded but its response was not read.
Application-level key The application associates a key with a logical operation and its result. Stripe documents this pattern for POST requests. For Stripe’s documented behavior, a later request using the same key receives the saved result once endpoint execution has begun and a result is saved.

The HTTP method tells clients and intermediaries about request semantics. A key gives an application a way to identify repeated attempts at a particular operation. An API may use both: clear method semantics where appropriate, plus key-based deduplication for operations whose retries need explicit tracking.

How Stripe’s idempotency-key behavior works

Stripe documents idempotency keys for POST requests. Its behavior is an implementation example, not a universal HTTP rule or a requirement that every API must follow. Stripe: Idempotent requests

Same key, same parameters

Stripe compares the parameters of a request with a reused key. If the parameters differ, Stripe returns an error rather than treating the changed request as the same operation. That check helps prevent accidental reuse of one key for two different intentions.

Which result gets replayed

Stripe saves the first result after endpoint execution begins and returns that result for later requests with the same key. Its documentation says this includes a 500 error. Repeating the request with the same key therefore replays the recorded result; it is not necessarily a way to make the operation run again and obtain a different outcome.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

When Stripe does not save a result

Stripe says it does not save an idempotent result when parameter validation fails or when a concurrent request conflict prevents endpoint execution from beginning. This boundary matters: a key protects retries according to the documented execution and persistence rules, rather than proving that every request attempt has a stored outcome.

Key retention

Stripe says keys may be pruned after they are at least 24 hours old. If a pruned key is reused, Stripe may treat the request as new and initiate another operation. Retention is therefore part of the API’s behavior, not an assumption that a key will deduplicate forever.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Designing key-based retries in your own API

Keep the key stable for one logical operation

Generate one key for the operation and reuse it for every retry of that operation. Mint a new key when the caller intends a genuinely new operation. If a retry receives a new key each time, the server cannot use key equality to recognize those attempts as duplicates.

Make key reuse unambiguous

Associate the key with the relevant request parameters or a canonical representation of the operation. Define what happens if a caller reuses a key with different parameters; Stripe’s documented approach is to reject that mismatch. Specify which response or error is replayed for a matching retry so clients can interpret the result consistently.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Specify execution, concurrency, and retention rules

Document when the server considers execution to have begun and when it records an outcome. Decide how simultaneous requests with the same key are handled, what happens when a conflict prevents execution, and how long keys and results remain available. These are application design choices; Stripe’s behavior provides a concrete example, not a protocol-wide answer.

For Stripe specifically, the documentation suggests a V4 UUID or another sufficiently random string and sets a maximum key length of 255 characters. Those are Stripe’s API details, not universal requirements for idempotency keys.

What idempotency does not guarantee

Idempotency is not a promise of “exactly once” delivery or exactly-once execution across an arbitrary distributed system. RFC 9110 defines equivalence in terms of the requested server effect and allows incidental per-request effects. Stripe’s documentation scopes result persistence to requests whose endpoint execution begins. Neither establishes a universal guarantee for external side effects or multi-service workflows.

If an operation triggers work in another service, sends a message, or causes a separate system to act, the API must account for that boundary in its own design. A request key alone does not establish that every downstream system has deduplicated its work or that all effects share one atomic outcome.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

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.