Idempotency Keys

An idempotency key lets a client safely retry a non-idempotent operation when the network outcome is unknown.

Accept an Idempotency-Key only when the server stores the request result or equivalent outcome, scopes keys to an operation and tenant, and rejects reuse with different parameters.

httpapireliabilityretries

Reference (http)

POST /payments HTTP/1.1
Idempotency-Key: 01J7EXAMPLE
Content-Type: application/json

Accept an Idempotency-Key only when the server stores the request result or equivalent outcome, scopes keys to an operation and tenant, and rejects reuse with different parameters.

Common mistakes

Calling a request idempotent merely because it has a key, or expiring keys before clients can safely resolve delayed retries.

Sources

MDN HTTP Reference