Idempotency keys

  ```infobox  # Idempotency keys    ## At a glance    | Property | Details |  | --- | --- |

− | What it is | A client-chosen identifier that lets a server recognise a retried request and return the original result instead of acting twice |

+ | 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. Idempotency keys make the retry safe in all three cases.

+ 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  

− The word comes from the HTTP specification, which classifies request methods by whether repeating them changes the result. 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 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)).    ## 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.  … 21 unchanged lines …  ### Retention    A stored key eventually expires, and after expiry a "retry" is a new request. Stripe removes keys "automatically after they're at least 24 hours old" and will "generate a new request if a key is reused after the original is pruned" ([Stripe](https://docs.stripe.com/api/idempotent_requests)). Adyen keys "are valid for a period of 7 to 14 days after first submission" ([Adyen](https://docs.adyen.com/development-resources/api-idempotency/)). PayPal says the server stores the ID "for a period of time" that depends on the API, and gives the refund endpoint as an example where "the user can make the call again with the same ID … for up to 45 days" ([PayPal](https://developer.paypal.com/api/rest/requests/)). The consequence for clients is that a retry window longer than the retention period is not protected, and an application that queues failed operations for later retry needs to know the number.    ### Parameter mismatch  

− Every documented implementation rejects a key reused with different content, but the signal differs. EC2 returns `IdempotentParameterMismatch` ([Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html)); Stripe "errors" ([Stripe](https://docs.stripe.com/api/idempotent_requests)); Square returns "an error indicating that you used the idempotency key previously", adding that "this behavior might vary depending on the API" ([Square, Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)). The IETF draft specifies `422 Unprocessable Content` with a problem-details title of "Idempotency-Key is already used" ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)).

+ Several documented implementations reject a key reused with different content, but the signal differs; the cited Adyen and PayPal pages do not state a mismatch rule. EC2 returns `IdempotentParameterMismatch` ([Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html)); Stripe "errors" ([Stripe](https://docs.stripe.com/api/idempotent_requests)); Square returns "an error indicating that you used the idempotency key previously", adding that "this behavior might vary depending on the API" ([Square, Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)). The IETF draft specifies `422 Unprocessable Content` with a problem-details title of "Idempotency-Key is already used" ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)).

    ### Concurrent retries    A retry can arrive while the original is still executing. The IETF draft separates this from mismatch and specifies `409 Conflict` with the title "A request is outstanding for this Idempotency-Key" ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)). Adyen documents that a duplicate submitted "before the first request has completed" returns "HTTP 422 – Unprocessable Entity or HTTP 409 - Conflict status with the error code 704: 'request already processed or in progress'" ([Adyen](https://docs.adyen.com/development-resources/api-idempotency/)). Stripe treats this case as one where no result is saved at all: if "the request conflicts with another request that's executing concurrently, we don't save the idempotent result because no API endpoint initiates the execution. You can retry these requests" ([Stripe](https://docs.stripe.com/api/idempotent_requests)).    ### Whether failures are replayed  … 24 unchanged lines …  **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.** The key makes a retry safe; it does not make it 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).

+ **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`.