Idempotency keys

  ```infobox  # Idempotency keys    ## At a glance    | Property | Details |  | --- | --- |  | What it is | A client-chosen identifier that lets a server recognise retries and apply a documented duplicate-request policy within a defined scope and retention window |  | Underlying idea | [Idempotent HTTP methods](https://httpwg.org/specs/rfc9110.html#idempotent.methods) in RFC 9110 |  | Common transport | An HTTP request header such as `Idempotency-Key` ([Stripe](https://docs.stripe.com/api/idempotent_requests)), a request parameter such as `ClientToken` ([Amazon EC2](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)), or a body field such as `idempotency_key` ([Square](https://developer.squareup.com/reference/square/payments-api/create-payment)) |  | Standardisation | IETF `Idempotency-Key` header draft, revision 07 (October 2025), [expired](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html) without becoming an RFC |  | Related | [Exponential backoff with jitter](/wiki/exponential-backoff-with-jitter) · [Idempotency and recovery in agent tool calls](/wiki/idempotency-and-recovery-in-agent-tool-calls) |  ```    An **idempotency key** is a unique value that a client attaches to a request that would otherwise not be safe to repeat, such as creating a payment or launching a server. The server uses the key—often together with a fingerprint of relevant request data—to recognise retries and apply a documented duplicate-request policy. That policy is provider-specific: it can replay a stored response, report the earlier operation's result, reject a mismatched or concurrent reuse, or ensure that an already successful operation is not performed again. The mechanism exists because network failures are ambiguous: a client that never receives a response cannot tell whether its request was lost, failed midway, or succeeded. Within a provider's documented scope and retention window, an idempotency key can let the client retry without repeating the protected server-side operation. It does not by itself guarantee end-to-end exactly-once behavior or make every ambiguous failure safe to retry. ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html); [provider comparison](#comparison))    The pattern is widely used in payment and cloud-infrastructure APIs, and each provider publishes its own contract. Those contracts agree on the core mechanism but differ on details that matter in practice: where the key is sent, what the key is scoped to, how long the server remembers it, what happens when a key is reused with different parameters, and whether a failed first attempt is replayed or re-executed. This article describes the shared mechanism, then compares those properties across documented implementations. It is about the API-level contract; recovery strategies built on top of it, such as checkpoints and reconciliation after an uncertain outcome, are covered in [Idempotency and recovery in agent tool calls](/wiki/idempotency-and-recovery-in-agent-tool-calls).    ## Background: idempotent methods in HTTP  

− Idempotence is a mathematical concept also used in computer science; HTTP applies it to request-method semantics ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)). RFC 9110 classifies methods by whether their intended effect on the server changes when an identical request is repeated. RFC 9110 states that "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", and lists `GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`, and `TRACE` as idempotent ([RFC 9110 §9.2.2](https://httpwg.org/specs/rfc9110.html#idempotent.methods)). Two qualifications in the same section shape everything that follows. First, idempotence is about the server's state, not the response: "the fact that a method is idempotent does not imply that each request will receive the same response status code." Second, "the definition of idempotent only considers the intended effect on the server and does not consider side effects such as the logging of requests, charges incurred on third-party servers, or an increase in advertisement counter statistics" ([RFC 9110 §9.2.2](https://httpwg.org/specs/rfc9110.html#idempotent.methods)).

+ Idempotence is a mathematical concept also used in computer science; HTTP applies it to request-method semantics ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)). RFC 9110 classifies methods by whether their intended effect on the server changes when an identical request is repeated. RFC 9110 states that "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", and lists `GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`, and `TRACE` as idempotent ([RFC 9110 §9.2.2](https://httpwg.org/specs/rfc9110.html#idempotent.methods)). Two qualifications in the same section shape everything that follows. First, idempotence concerns the intended effect of repeating a request; the response can differ. Second, the property applies only to what the user requested: a server can separately log each request, retain revision history, or perform other non-idempotent side effects for each idempotent request ([RFC 9110 §9.2.2](https://httpwg.org/specs/rfc9110.html#idempotent.methods)).

    `POST` is the notable omission: HTTP does not define the method itself as idempotent. A particular resource can still give a `POST` idempotent semantics. RFC 9110 therefore says a client should not automatically retry a non-idempotent method unless it knows the request semantics are actually idempotent or can detect that the original request was never applied. Idempotency keys are a common application-level contract for making retries of particular `POST` operations safer; they do not change the semantics of every `POST`. Stripe's documentation makes its own boundary explicit: "All `POST` requests accept idempotency keys. Don't send idempotency keys in `GET` and `DELETE` requests because it has no effect. These requests are idempotent by definition" ([RFC 9110 §9.2.2](https://httpwg.org/specs/rfc9110.html#idempotent.methods)) ([Stripe, Idempotent requests](https://docs.stripe.com/api/idempotent_requests)).    ## The problem: ambiguous failures    A retry is only dangerous when the client cannot tell what happened to the original request. Brandur Leach, writing for Stripe in 2017, enumerated the cases: "The initial connection could fail as the client tries to connect to a server. The call could fail midway while the server is fulfilling the operation, leaving the work in limbo. The call could succeed, but the connection break before the server can tell its client about it" ([Leach, Designing robust and predictable APIs with idempotency](https://stripe.com/blog/idempotency)). From the client's side all three look identical: a timeout or a dropped connection. Retrying blindly is correct in the first case, ambiguous in the second, and creates a duplicate in the third.  … 50 unchanged lines …  ## Standardisation    The IETF HTTP APIs working group adopted a draft, *The Idempotency-Key HTTP Header Field*, by Jayadeba Jena and Sanjay Dalal, whose abstract states that the header "can be used to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant". Revision 07 is dated 15 October 2025, defines the field as an Item Structured Header whose "value MUST be a String", and had expired by April 2026 without progressing to an RFC ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)). Its main contributions are the vocabulary used above, in particular the fingerprint concept and the separation of the mismatch case (`422`) from the in-progress case (`409`). Whether the working group revives the draft is not known at the time of writing; the provider contracts in the table predate it and do not depend on it.    ## Design considerations and limitations  

− **Keys are not end-to-end exactly-once delivery.** An idempotency key protects one hop: the client's request to one server. If that server calls a third party, RFC 9110's exclusion of "charges incurred on third-party servers" applies, and the downstream call needs its own key or its own reconciliation ([RFC 9110 §9.2.2](https://httpwg.org/specs/rfc9110.html#idempotent.methods)). Keys also do nothing for operations that were never sent, so a client that crashes between generating a key and sending the request must persist the key first if it wants to resume.

+ **Keys are not end-to-end exactly-once delivery.** An idempotency key protects the operation covered by the server's documented contract, not every downstream effect. RFC 9110's method-level definition allows a server to perform non-idempotent side effects for an idempotent request. As an engineering inference, when a server calls another independently retried service, that downstream operation needs its own duplicate-suppression or reconciliation mechanism if repeated effects would violate the end-to-end goal; an upstream provider's key contract does not automatically extend beyond its documented scope ([RFC 9110 §9.2.2](https://httpwg.org/specs/rfc9110.html#idempotent.methods); [IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)). Keys also do nothing for operations that were never sent, so a client that crashes between generating a key and sending the request must persist the key first if it wants to resume.

    **Retention bounds the retry window.** Because keys expire, a client should retry within the documented window and treat anything later as a new operation requiring a fresh check of the server's state, for example by querying for the resource before creating it.    **A replayed error is still an error.** Where failures are cached, the retry returns the original failure. The client has to decide whether to issue a new key, and it should do so only after establishing that the original did not take effect; Stripe's rule that results are stored only once execution begins means a stored `500` may correspond to a partially completed operation.    **Keys should carry no meaning.** Random keys with enough entropy avoid collisions and, as Stripe notes, avoid leaking personal identifiers into server-side logs ([Stripe](https://docs.stripe.com/api/idempotent_requests)). Deriving a key deterministically from the operation's content is sometimes done so that independent processes converge on the same key, but it turns the key into a fingerprint and reintroduces the collision and privacy questions the random approach avoids.    **Retries still need pacing.** Where the provider contract prevents duplicate execution, the key can make a retry safer; it does not make the retry cheap. Leach's post pairs idempotency with exponential backoff, waiting a time proportional to "2^n, where n is the number of failures", and adds "random 'jitter' to each client's wait time" so that aligned retry schedules do not overwhelm a recovering server ([Leach](https://stripe.com/blog/idempotency)). See [Exponential backoff with jitter](/wiki/exponential-backoff-with-jitter).    ## Related subjects    - [Idempotency and recovery in agent tool calls](/wiki/idempotency-and-recovery-in-agent-tool-calls): checkpoints, reconciliation, and completion verification built on top of the contract described here.  - [Exponential backoff with jitter](/wiki/exponential-backoff-with-jitter): the pacing half of a safe retry policy.  - [Content-addressed storage](/wiki/content-addressed-storage): digests as identifiers, the idea behind idempotency fingerprints.  - [Exactly-once delivery](/wiki/exactly-once-delivery): the broader distributed-systems problem that idempotency keys partially address.  - [HTTP request methods](/wiki/http-request-methods): the safe and idempotent method classes that idempotency keys extend to `POST`.