Idempotent Requests

Some endpoints, such as create order v2, support idempotency for safely retrying requests without unintentionally repeating an operation. This is useful for when you do not receive a response, due to a network error for example.

To perform an idempotent request, provide an Idempotency-Key: <key> header in the request.

An idempotency key is any unique client-generated value with sufficient entropy to avoid collisions. We recommend using V4 UUIDs as your keys.

For idempotent requests, the API saves the status code and body of the response of the initial request and, when the same idempotency key is used in another request, it replays the saved response. This includes error responses such as 400 and 500 errors. The following validation is also performed for idempotent requests:

• If the request parameters do not match the initial request, we will return an Unprocessable Entity error
• If the initial request is still being processed concurrently and has not yet responded, we will return a Conflict
  error

When a response is replayed, an Idempotent-Replayed: true header will be attached to the response.

Idempotency keys will be removed once they are at least 24 hours old, after which a key may be reused and will be processed as an initial request and response.