Skip to main content

Overview

The X-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.
If the header is missing on an endpoint that requires it, the API returns 400 with INVALID_DATA:
If the key is blank or longer than 255 characters, the API returns 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 returns 409 Conflict:
The same 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 returns 400 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 a 400 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 an externalId 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:
If the list is empty, the first request may still be running: look again after 30 seconds. If it is still empty then, the first request did not create an operation. Send the request again with a new key. See Filtering for the filter syntax.

Examples

Generate a UUID v4 for each unique operation:
Retrying after a timeout:
Never reuse an idempotency key for a different operation. Each unique operation must have its own key, or the API rejects it with IDEMPOTENCY_KEY_PARAMETERS_MISMATCH.