Overview
TheX-Idempotency-Key header protects against duplicate operations when you retry a request after a timeout or a network failure. When the API sees a key it already processed for the same request, it does not run the request again.
A retry does not return the original response. It answers 409 Conflict, and you recover the original operation by its externalId. See Retry safely.
How it works
Which endpoints use the header
The header is a per-endpoint behavior, not a rule for every mutating request.
GET and DELETE requests never use the header. Sending the header to an endpoint that ignores it is harmless.
The X-Idempotency-Key header
Send a key you generate on every request to an endpoint that requires it.- The key is any non-blank string of up to 255 characters. A UUID is a good choice, but it is not required.
- Keys are scoped to the authenticated caller. Another caller can use the same key without interference.
- A key is remembered for 24 hours from the first response. After that, the same key is treated as new and runs the request again.
400 with INVALID_DATA:
400 with INVALID_DATA and the error code INVALID_IDEMPOTENCY_KEY in details.errors.
What happens on a repeat
The API compares each request that reuses a key with the first one. Two requests are the same when they have the same method, path, query parameters and body. For JSON bodies, field order and whitespace do not matter.Same key, same request
The API does not create a second operation. It returns409 Conflict:
409 is returned while the first request is still running. The API holds the key for up to 30 seconds in that case.
Same key, different request
If the method, path, query parameters or body differ from the first request, the API returns400 with IDEMPOTENCY_KEY_PARAMETERS_MISMATCH. Sending the same body to a different endpoint counts as a different request.
A request that fails
A request that ends in an error, such as a400 validation error or a 422 business rule violation, releases its key. You can fix the problem and send the request again with the same key, and it runs as a new request.
Retry safely
Always send anexternalId in the request body of operations, and use a value that is unique in your system. It is the identifier you use to find the operation again. The API does not enforce that it is unique, so reusing a value returns every operation that carries it.
When a retry answers 409 with IDEMPOTENCY_KEY_CONFLICT, the first request already reached the API. Look the operation up by externalId instead of sending it again:
Examples
Generate a UUID v4 for each unique operation:- Python
- JavaScript