Idempotency keys

  ```infobox  # Idempotency keys    ## At a glance    | Property | Details |  … 30 unchanged lines …  **The server stores the key with the outcome.** Stripe's description is representative: the layer works "by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeds or fails. Subsequent requests with the same key return the same result, including `500` errors" ([Stripe](https://docs.stripe.com/api/idempotent_requests)). PayPal describes the same behaviour from the caller's perspective: if "the initial call fails with the HTTP `500` status code but the server has already refunded the payment, the caller does not need to worry that the server will refund the payment again" ([PayPal, API requests](https://developer.paypal.com/api/rest/requests/)).    **The server checks that a replay really is a replay.** A key reused by accident on a different operation must not silently return an unrelated stored response. Implementations therefore compare the retry's parameters against the original. Stripe's layer "compares incoming parameters to those of the original request and errors if they're not the same to prevent accidental misuse" ([Stripe](https://docs.stripe.com/api/idempotent_requests)); EC2 fails the retry "with an `IdempotentParameterMismatch` error" ([Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html)). The IETF draft generalises this comparison as an *idempotency fingerprint*, which a server may derive from a checksum of the payload, selected fields, or a request digest or signature ([IETF draft-ietf-httpapi-idempotency-key-header-07](https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html)). A fingerprint is a digest used to identify content, the same idea that underlies [content-addressed storage](/wiki/content-addressed-storage), applied here to a request rather than a stored artifact.    ## The contract: properties that vary between implementations  

− Providers agree on the mechanism above but not on its parameters. Five properties determine what a client can actually rely on, and they should be read from each provider's documentation rather than assumed.

+ Providers agree on the mechanism above but not on its parameters. Six properties—transport plus the five discussed below—determine what a client can actually rely on, and they should be read from each provider's documentation rather than assumed.

    ### 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/AWSEC2/latest/APIReference/Run_Instance_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  … 45 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`.