Overview
Idempotency ensures that performing the same operation multiple times produces the same result as performing it once. This protects against duplicate operations when requests are retried due to timeouts or network failures.
How it works
Mutating endpoints (POST, PUT, PATCH) require the X-Idempotency-Key header. This client-generated key lets the API detect and deduplicate repeated requests.
When it is required
The X-Idempotency-Key header is required on any request that creates or modifies a resource. GET and DELETE requests do not require it.
Conflict behavior
If a request arrives with an idempotency key that was already used, the API returns HTTP 409 Conflict:
Examples
Generate a UUID v4 for each unique operation:
Retrying safely after a timeout:
Never reuse an idempotency key for a different operation. Each unique operation must have its own key.
