Our API supports idempotency for safely retrying requests without performing the same operation twice. This is particularly useful when creating or updating objects, especially if a connection error occurs. To use idempotency, provide an Idempotency-Key in the request headers. The server saves the status code and body of the first request made with a given idempotency key.
Idempotency keys should be unique. We recommend using V4 UUIDs or another random string with enough entropy to avoid collisions. Keys can be up to 255 characters long.
The system automatically removes keys after 24 hours. If a key is reused after the original is pruned, a new request is generated. The idempotency layer compares incoming parameters to those of the original request and errors if they’re the same to prevent accidental misuse. If this occurs, the server responds with a 422 Unprocessable Entity error, indicating that the parameters conflict with the original request. For instance, a 409 Conflict will be returned if a request conflicts with another concurrent operation, including a retry-after header to suggest when the client should retry. Results are saved only after the execution of an endpoint begins. If incoming parameters fail validation or the request conflicts with a concurrent request, the idempotent result is not saved, and you can retry these requests. In such cases, the server ensures that no unintended side effects occur.
We recommend implementing a retry strategy such as exponential backoff in the client to handle timeouts or transient failures.
All POST requests accept idempotency keys. Don’t send idempotency keys in GET and DELETE requests as these are inherently idempotent.