Source: Idempotent requests (Stripe API reference)
Stripe's reference design for idempotency keys: client-generated keys, saved first response, parameter-mismatch errors, 24-hour pruning, and which requests need keys.
Contents
- What: API reference page
- Publisher: Stripe
- Date: accessed 2026-11-14
- Original: Idempotent requests
Summary
The canonical industry pattern for making a side-effecting API call safe to retry. The client attaches a unique key; the server stores the outcome of the first execution under that key and returns it for repeats, so a retried create or update does not happen twice.
Key claims
- Keys are client-generated (V4 UUIDs suggested), up to 255 characters, and should not contain sensitive data.
- API v1 saves the status code and body of the first request once endpoint execution begins; retries return that saved response, including
500errors. API v2 instead drives failed or partial work to completion on retry. - Keys can be pruned after at least 24 hours; a reused key after pruning creates a new request.
- Reusing a key with different parameters is an error.
- Requests that fail validation or conflict with a concurrent request using the same key are not saved and can be retried.
- All v1
POSTrequests accept keys;GETandDELETEare idempotent by definition.