Idempotency
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.Configuration
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:Copied1Idempotency-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.