Idempotency of GET and DELETE requests
Idempotency is a Web API design principle defined as the ability to apply the same operation multiple times without changing the result beyond the first try. The Stripe API guarantees the idempotency of
DELETE requests, so it’s always safe to retry them. Because a certain amount of intermittent failure is to be expected, clients need a way of reconciling failed requests with a server, and idempotency provides a mechanism for that. Including an idempotency key makes
POST requests idempotent, which prompts the API to do the record keeping required to prevent duplicate operations. Clients can safely retry requests that include an idempotency key as long as the second request occurs within 24 hours from when you first receive the key (keys expire out of the system after 24 hours). For example, if a request to create a charge doesn’t respond because of a network connection error, a client can retry the request with the same idempotency key to guarantee that no more than one charge is created.
Sending idempotency keys
Idempotency keys are sent in the
Idempotency-Key header, and you should use them for all
POST requests to the Stripe API. Most official client libraries can send them automatically as long as they’re configured to send retries.
If you decide to send them manually, make sure that the tokens being used are sufficiently unique to unambiguously identify a single operation within your account over at least the last 24 hours. Two common strategies for generating idempotency keys are to:
- Use an algorithm that generates a token with enough randomness, like UUID v4.
- Derive the key from a user-attached object like the ID of a shopping cart. This provides a relatively straightforward way to protect against double submissions.
You can identify a previously executed response that’s being replayed from the server by the header