Idempotent Requests

Autopilot APIs support idempotency for safely retrying requests without accidentally performing the same action twice. When creating an object, use an idempotency key to retry the action safely in case of failures or network errors. For example, in the case of a network timeout, it is possible that the request is successfully accepted by Autopilot, and an idempotency key can guarantee that the request is processed only once.

To further minimize unwanted side effects when requests are duplicated, you can take the following actions in your integration with Autopilot:

• Implement asynchronous server-to-server webhooks. This approach will help keep track of potentially missed responses.
• Use idempotency in your API requests. The Autopilot API supports idempotency on POST requests.

Note

Other request types (such as GET, DELETE, and PUT) are idempotent by definition.

Using Idempotent Requests

To submit a request for idempotent processing, send a request with the X-Idempotency-Key: <KEY> value in the header.

The <KEY> must be exactly 36 characters (the length of a UUID with dashes). We highly recommend using a cryptographically secure UUID generator. If you do not receive a response (for example, due to a network timeout), you can safely retry the request with the same HTTP header.

To verify a request was processed idempotently, check the X-Idempotency-Key returned in the response. If a cached version of a request was returned (for example, in the case of a retry), X-Idempotency-Relayed: true is also returned.

Key Scope and Validity Duration

Keys are scoped to each API method and URL endpoint. Idempotency keys are valid for a minimum period of 24 hours after the first request.