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/AWSEC2/latest/APIReference/Run_Instance_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 records the key together with the outcome of the first request that carried it. If the client retries with the same key, the server recognises the retry and returns the recorded outcome rather than performing the operation 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.    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)).  

− `POST` is the notable omission. A `POST` that creates a resource creates another one if repeated, so HTTP clients cannot retry it automatically. Idempotency keys are the conventional way to give a specific `POST` endpoint the retry safety that the method as a whole lacks. Stripe's documentation makes the 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" ([Stripe, Idempotent requests](https://docs.stripe.com/api/idempotent_requests)).

+ `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.    Amazon's EC2 documentation describes the same problem from the infrastructure side. Mutating requests "typically return a result before the operation's asynchronous workflows have completed", operations "might also time out or encounter other server issues before they complete, even though the request has already returned a result", and if "the original request and the subsequent retries are successful, the operation is completed multiple times. This means that you might create more resources than you intended" ([Amazon EC2, Ensuring idempotency](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html)).  … 65 unchanged lines …    - [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`.