Idempotency Key

An idempotency key is a unique, client-generated identifier for one logical API operation, such as creating or updating an object. A server that supports this mechanism uses the key to recognize retries of that operation, helping prevent repeated requests from producing duplicate effects. It identifies the operation, not the caller.

How an Idempotency Key Works

The need arises when a connection fails or a response is lost. The client may not know whether the server completed the action before communication stopped. A missing response is therefore not proof that nothing happened. Sending the operation again without suitable retry handling risks repeating work that already succeeded.

The client generates an idempotency key for the intended operation and sends it with the original request. If the outcome is uncertain and the API supports this retry mechanism, the client retries the same operation using the same key. The server correlates that retry with the earlier operation and applies its documented recovery behavior. Avoiding duplicate side effects depends on this server-side handling, not merely on including an identifier.

The key belongs to the logical operation, not to each transmission attempt. Generating a fresh key for a retry breaks that association; conversely, a genuinely different operation needs a distinct key. Reusing a key is not a way to submit changed instructions as though they were the original request. Stripe API v1, for example, rejects reuse of a key with different request parameters.

Before relying on an idempotency key, check the provider's rules for the endpoint and API version: whether keys are supported, how long records are retained, whether parameters are checked, and how retries are resolved. These details determine the protection available after an uncertain response.

Provider Rules and Retry Limits

Stripe API v1 saves the first executed request's status code and response body under the key, including a 500 response. Subsequent matching requests using that key receive the saved result. Keys may be pruned after at least 24 hours; reusing one after pruning is treated as a new request. That retention rule should not be assumed for other providers.

Stripe API v2 handles recovery differently: successful operations are not repeated, partially failed work may be completed, and an error is returned when retry cannot succeed. Its behavior is not simply API v1's saved-response model. Finite retention and dependence on correct implementation mean that an idempotency key alone is not a universal, permanent guarantee of exactly-once execution.

Idempotency Keys vs. API Keys and HTTP Idempotence

• Purpose: An API secret key authenticates requests and determines which resources an integration can access; an idempotency key identifies an operation for retry handling. The latter does not replace authentication.
• HTTP Semantics: RFC 9110 defines an idempotent method by the same intended effect from multiple identical requests as from one request. PUT, DELETE, and safe methods are idempotent under these semantics, whereas application-level key handling depends on endpoint support.
• Response Expectations: HTTP idempotence does not require identical responses, only the same intended effect. Returning a saved response is Stripe API v1's implementation behavior, not the definition of idempotence.

A key mechanism does not make every POST endpoint safe to retry. After an uncertain communication failure, do not automatically retry a non-idempotent method unless you can establish that the operation's actual semantics are idempotent or that the original request was not applied.