IdempotencyKey

IdempotencyKey is a client-supplied value used by APIs to recognize duplicate requests and apply them only once. It helps ensure that repeated operations, such as retries after a timeout or network interruption, do not produce unintended side effects like duplicate charges or multiple resource creations.

How it works: when a client initiates a state-changing operation, it generates a unique idempotency key and sends it with the request. The server records the key along with the operation outcome. If another request arrives with the same key within a defined idempotency window, the server returns the previously recorded result instead of re-executing the operation. If the key is new, the server processes the request and stores the resulting outcome for future retries.

Usage and scope: idempotency keys are commonly used for POST or PUT operations that modify server state, particularly in payment processing, order creation, and other critical actions. The length and format of the key, as well as the length of the idempotency window, vary by system. Keys should be unique per logical operation, not per request.

Design considerations: keys should be generated with sufficient entropy to avoid collisions, yet remain stable for the duration of the operation. Systems must balance storage requirements with the desired window of deduplication. Considerations include how to handle retries after partial failures, how to store and purge old keys, and how to secure keys to avoid leakage of sensitive operation details.

Limitations: idempotency is effective within a centralization boundary; it may not prevent duplicates across distributed services or after data replication delays. It complements, but does not replace, other reliability and validation mechanisms.

Examples: Stripe uses an Idempotency-Key header to achieve these guarantees; many cloud and payment APIs offer similar mechanisms. See also idempotence, retries, and deduplication.