Idempotency keys

  ```infobox  # Idempotency keys    ## At a glance    | Property | Details |  … 38 unchanged lines …  ### Scope    The key is unique within some boundary, and the boundary is provider-defined. Adyen states that "keys are stored at a company account level. The system checks that the idempotency keys are unique to the company account" ([Adyen](https://docs.adyen.com/development-resources/api-idempotency/)). Square requires that keys "be unique for every `CreatePayment` request", which scopes them to an operation type ([Square, CreatePayment](https://developer.squareup.com/reference/square/payments-api/create-payment)). EC2 distinguishes *regional* idempotency, where "you can use the same request, including the same client token, in a different Region", from *zonal* idempotency, where two `AllocateHosts` calls with the same token "succeed if they specify different values for the `AvailabilityZone` parameter" ([Amazon EC2](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)). The IETF draft leaves the choice open: "uniqueness of the key MUST be defined by the resource owner and MUST be implemented by the clients of the resource" ([IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)).    ### Retention  

− A stored key eventually expires, and after expiry a "retry" is a new request. For API v1, 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.

+ A stored key eventually expires, and after expiry a "retry" is a new request. For API v1, 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. Google AIP-155, which is design guidance for Google APIs rather than a provider-wide runtime guarantee, permits an API to choose any reasonable timeframe for honoring request IDs; the particular API therefore has to document the effective window. ([Google AIP-155](https://google.aip.dev/155))

    ### Parameter mismatch    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/ec2/latest/devguide/ec2-api-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/)). For API v1, 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  

− This is the property most often assumed and least often checked. Stripe's API v1 saves and replays the first result once execution starts, including `500` errors, but does not store validation failures ([Stripe](https://docs.stripe.com/api/idempotent_requests)). Stripe's API v2 instead documents that retries do not repeat successful operations and that failed or partially failed work is retried to completion when possible; if a retry cannot succeed, Stripe returns an error explaining why. The page does not specify a single failure-replay rule shared by both versions. EC2's guidance describes idempotency in terms of successful completion, "if the original request completes successfully, any subsequent retries complete successfully without performing any further actions", and separately advises retrying 500-series responses with backoff and not retrying most 400-series responses ([Amazon EC2](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)). Adyen and PayPal do not state whether failed first attempts are replayed. Under Stripe API v1, a client that retries a cached `500` with the same key receives the same `500` again; whether that is the desired behaviour depends on whether the failure was transient, which the client cannot always know.

+ This is the property most often assumed and least often checked. Stripe's API v1 saves and replays the first result once execution starts, including `500` errors, but does not store validation failures ([Stripe](https://docs.stripe.com/api/idempotent_requests)). Stripe's API v2 instead documents that retries do not repeat successful operations and that failed or partially failed work is retried to completion when possible; if a retry cannot succeed, Stripe returns an error explaining why. The page does not specify a single failure-replay rule shared by both versions. EC2's guidance describes idempotency in terms of successful completion, "if the original request completes successfully, any subsequent retries complete successfully without performing any further actions", and separately advises retrying 500-series responses with backoff and not retrying most 400-series responses ([Amazon EC2](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)). Adyen and PayPal do not state whether failed first attempts are replayed. Under Stripe API v1, a client that retries a cached `500` with the same key receives the same `500` again; whether that is the desired behaviour depends on whether the failure was transient, which the client cannot always know. Google AIP-155 adds a different success-response edge case: a duplicate should ordinarily return the previously successful response, but if historical data is no longer retained after the resource has changed, the method may return the resource's current state instead. Thus even a deduplicated successful retry need not be byte-for-byte identical to the original response. ([Google AIP-155](https://google.aip.dev/155))

    ### Comparison    | Implementation | Transport | Scope | Retention | Mismatched retry | Concurrent retry | Failures replayed? |  | --- | --- | --- | --- | --- | --- | --- |  | [Stripe](https://docs.stripe.com/api/idempotent_requests) | `Idempotency-Key` header, ≤255 chars | Not stated on the page | API v1: pruned after ≥24 h; later reuse is a new request. API v2: not stated on the page | API v1: error. API v2: not stated on the page | API v1: not stored; retry allowed. API v2: not stated on the page | API v1: first result replayed after execution begins, including `500`; validation failures not stored. API v2: successful operations are not repeated; failed or partial work is retried to completion when possible |  | [Amazon EC2](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html) | `ClientToken` parameter, ≤64 ASCII chars | Regional or zonal, per action | Not stated on the page | `IdempotentParameterMismatch` | Not stated | Framed around successful completion; 5xx should be retried with backoff |  | [Adyen](https://docs.adyen.com/development-resources/api-idempotency/) | `idempotency-key` header, ≤64 chars | Company account | 7–14 days after first submission | Not stated | `422` or `409`, error code 704 | Not stated |  | [PayPal](https://developer.paypal.com/api/rest/requests/) | `PayPal-Request-Id` header | Per API; not all APIs support it | "For a period of time", API-dependent; refund example: up to 45 days | Not stated | Not stated | Documented example: `500` after a completed refund is not repeated |  | [Square](https://developer.squareup.com/reference/square/payments-api/create-payment) | `idempotency_key` body field, ≤45 chars, required | Per `CreatePayment` request | Not stated | Error; "might vary depending on the API" | Not stated | Not stated |

+ | [Google AIP-155](https://google.aip.dev/155) | `request_id` request-message field; UUID4, restricted to 36 ASCII chars | The request message to which the field applies | Any reasonable timeframe; API-defined | Not stated | Not stated | Duplicate should return the previous successful response; current resource state may replace a stale historical response |

  | [IETF draft-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html) | `Idempotency-Key` structured header, string value | Defined by the resource owner | Resource "MAY" expire keys and should document the policy | `422` | `409` | Not specified |  

− "Not stated" means the cited page does not say; the provider may document it elsewhere or behave in an undocumented way. The table reflects the cited pages as retrieved in September 2026, with Stripe's version-specific contract refreshed in October 2026.

+ "Not stated" means the cited page does not say; the provider may document it elsewhere or behave in an undocumented way. The table reflects the cited pages as retrieved in September–October 2026, with Stripe's version-specific contract refreshed and Google AIP-155 added in October 2026.

    ## 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 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 the contract replays errors.** Under Stripe API v1, the retry returns the saved response, including a saved `500`, once endpoint execution has begun. The client should not switch to a new key unless it has established that repeating the logical operation is safe. Stripe API v2 has a different documented contract: retries do not repeat successful operations and may continue failed or partially failed work. Client recovery logic therefore has to bind itself to the API version and provider contract rather than assuming one Stripe-wide failure rule. [Stripe](https://docs.stripe.com/api/idempotent_requests)    **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`.