Idempotency-Key

What is the Idempotency-Key header?

The Idempotency-Key request header is a custom (non-standard but widely adopted) header sent by clients to ensure that a request is processed exactly once, protecting against network glitches and double-submits. Its semantics are described in the IETF Internet-Draft draft-ietf-httpapi-idempotency-key-header, which has not become an RFC.

API Usage & Best Practices

• Generate unique keys: Clients should send a UUID or unique key for each write request (POST, PATCH).
• Return cached results: If the server receives a request with a key it has already processed, it returns the cached response rather than running the business logic again.
• Payload check: If a key is reused with a different payload, reject with 422 Unprocessable Content, as the draft recommends. See idempotency key conflict.
• In-flight check: If a retry arrives while the original request with that key is still being processed, reject with 409 Conflict and a Retry-After.
• Missing key: If an operation requires the header and the request omits it, the draft recommends 400 Bad Request.

Examples

POST /v1/charges HTTP/1.1
Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type: application/json