Introduction

Idempotency refers to the property of an operation that produces the same result regardless of how many times it is executed. In other words, whether the operation is performed once or multiple times (five times, for example), the outcome remains unchanged after the initial application.

When idempotence guarantees are applied to methods that are not inherently idempotent (such as POST and PATCH), clients can safely retry requests knowing that each will be processed only once. In this scenario, concurrent requests sharing the same idempotency key may compete for execution, but exactly one will succeed and be processed.

How To Use

To enable idempotency, each request must include the Idempotency-Key header. Refer to the API Reference for the endpoints that support this header. It is expected for each key to be unique to differentiate new requests from the ones that are being retried.

The recommended format for the key is a UUID v7 or ULID, although ensuring uniqueness is the client’s responsibility.

Idempotency keys are retained by the system by default for 24 hours. After this period, requests should not be retried using the same key.

How To Interpret Responses

When processing successful responses for idempotent requests (those including the Idempotency-Key header), check the header Idempotent-Replayed:

• false: This is the first received request, the one that was processed by the backend API.
• true: This is a subsequent request that returned the (cached) response generated by the first request.

When processing unsuccessful responses (4XX and 5XX) for idempotent requests (those including the Idempotency-Key header), check the header Idempotent-Retriable:

• false: The request should not be retried with the same idempotency key. Because subsequent requests will return the same result.
• true: The request can, and should, be retried with the same idempotency key. Clients should wait a certain backoff delay before retrying again. Is important to use the same idempotency key so the system can properly identify retries and manage idempotency correctly.

Below is a diagram of the headers that can be expected when using the Idempotency Key in requests:

Error Handling And Retry

When using idempotency in requests, two additional status codes are expected. Note that error responses (e.g. 4XX, 5XX) returned by the server can also be cached and will be returned for subsequent requests using the same idempotency key.

• 409: The server already received a request with the same idempotency key, but is still processing the response. Clients should retry the request with the same key after a certain delay.
• 422: The server has already received the same idempotency key, but it was associated with a different request, which is not allowed. A request is uniquely identified by three components: request body, the URI and the HTTP method. This means that, two requests are considered identical if all three match; otherwise, they are treated as different. Clients should retry the request, but with a different idempotency key.

Note that these responses won't have the header Idempotent-Replayed present.