A network timeout leaves you guessing whether a write landed. Send an Idempotency-Key header and retrying becomes safe: the first request with a key does the work and its response is stored for 24 hours; a retry with the same key and the same body gets that stored response back, marked Idempotent-Replayed: true, instead of doing the work again. The header is optional on most write endpoints — leave it out and requests behave exactly as before. A few newer endpoints require it.

​
How it works

1

Generate a key per operation

Any string of 1 to 255 characters; a UUIDv4 is recommended. Use the same key for every retry of one operation, and a new key for a new operation.
2

Send it as a header

Here FILEAI_BASE_URL is https://api.orion.file.ai/prod/v1, or your regional host.
3

Retry with the same key and body

On a timeout, 429 or 5xx, resend the identical request. If the original had already finished, you get its response with Idempotent-Replayed: true and nothing is done twice.

​
What counts as the same request

Keys are scoped to your workspace and API key: the same key string sent with a different API key, or in a different workspace, is a different key. (Workspace-scoped keys are further scoped to the project in x-project-id.) Within that scope, fileAI fingerprints the request from its method, path, workspace and body. The body is compared in canonical form, so key order and whitespace don’t matter. The query string is not part of the fingerprint.

​
Outcomes

A request is only treated as “still running” for 120 seconds. If the original takes longer than that, a retry with the same key is allowed to run again. For slow operations, wait before retrying, or check the resource first.

​
Large responses

Responses larger than about 100 KB aren’t stored. The request is still recorded as finished, so a retry does not run it again; instead it gets a short placeholder at the original status:
Fetch the resource you created to read its full state.

​
Which errors are cached

An error raised by the endpoint itself is stored and replayed like a success, so a retry under the same key returns the same error. This covers 404, a 403 raised by the endpoint itself, and most 409 and 422 responses. These are not stored, so a retry under the same key runs again:
  • 401, and 403 from the API key check (READONLY_KEY, an inactive key, or no access to the project): these are rejected before idempotency runs;
  • every 5xx;
  • 408, 425 and 429;
  • errors whose code is VALIDATION_FAILED, BAD_REQUEST, BATCH_PARTS_TOO_LARGE or AGENT_RUN_IN_PROGRESS;
  • a success that reports a server-side failure for part of the request (an item in results with a 5xx error.status, or a non-empty failedDirectoryIds).
Some 400 and 422 errors are raised internally without an explicit code. Their response still shows BAD_REQUEST or VALIDATION_FAILED, but they are stored, so retrying with the same key returns the same error for 24 hours. After fixing the request, send it with a new key.
Idempotency fails open: if its store is briefly unavailable, the request still runs, without idempotency. Keep your own bookkeeping for operations where a duplicate would be costly.

​
Where it applies

The header is honored on every POST, PATCH, PUT and DELETE request that isn’t multipart/form-data, with these exceptions.

​
Required

​
Accepted but ignored

These accept the header but never store or replay: every call runs fresh, with no Idempotent-Replayed header and no key-reuse 422. Because extract, split and classify ignore the key, a retried submit creates a second job. Use client_ref to recognize duplicates on your side.

​
Special handling

  • POST /v1/files/upload/batch runs its own idempotency: a replay re-signs the presigned URLs instead of returning expired ones.
  • POST /v1/files/upload/multipart/complete/batch stores per-item server errors too, because completing an upload can’t be repeated. To retry a failed item, send it as a new request with a new key.

Errors

IDEMPOTENT_REQUEST_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED and when to retry.

Async jobs

Submit work once and track it to completion.

Agent sessions

The endpoints where the key is required.

Uploads

Batch and multipart uploads and their retry rules.