The Airplane API supports idempotency which allows clients to safely retry requests without the risk of duplicating operations.
To take advantage of this, clients must include an Idempotency-Key header in their requests. This header is used to uniquely identify an API request across multiple retries. Airplane will store this identifier and ensure future requests with the same identifier are not processed again.
For example, say a client issues an HTTP request to execute a task via POST /v0/tasks/execute. The Airplane API receives the request, starts executing the task, but a network error prevents the API from responding to the client. The client can safely retry the request with the same Idempotency-Key and the API server will return the original request's response instead of re-executing the task.


All GET, PUT, and DELETE methods are safe to retry without any additional client logic. It is still safe to send an Idempotency-Key header with those requests, but it will have no effect.
For POST and PATCH requests, a client should generate a random UUID for each API request and send it via an Idempotency-Key header. For example:
Idempotency-Key: 4ff56c9a-c216-4cfa-84fe-e7a3aa887b84
The Airplane SDKs automatically generate this header and use it for retries.
Idempotency keys are only stored if a request returns a successful (2xx) HTTP status code. It is recommended to retry API requests that return a 429 or 5xx status code (excluding 501). HTTP responses that return a 429 status code will include a Retry-After header that identifies how long clients should wait before retrying.
The Airplane API retains idempotency keys for one hour. If a request is retried more than one hour after the initial request then it will be executed as if it was the first attempt.
If a POST or PATCH HTTP request includes an idempotency key, the HTTP response will include an Idempotency-Key header with an identical value in the response.