Every error from the fileAI API is an RFC 9457 problem document, served as Content-Type: application/problem+json. Each one carries a stable code to branch on and a requestId to quote when you contact support.

How it works

Branch on code, not on detail or title. Codes are a public contract: new ones can be added, but existing ones are never renamed or repurposed. detail is prose for humans and can change at any time. For unexpected server errors (INTERNAL_ERROR), detail is always the generic An internal error occurred. — the cause is in fileAI’s logs under your requestId.

Request ids

Every response, success or error, carries an X-Request-Id header, and errors repeat it as requestId. fileAI picks it in this order:
  1. The X-Request-Id header you sent, if any — so you can use your own correlation ids.
  2. The trace id from a W3C traceparent header, if you sent a valid one.
  3. A newly generated id.

Rate limits

A 429 RATE_LIMITED response includes a retryAfter member (seconds) and a Retry-After header with the same value. Responses also carry RateLimit and RateLimit-Policy headers, for example "default";r=<remaining>;t=<seconds>, so you can slow down before you hit the limit. See Rate limits for every header.

Example

Send an Idempotency-Key on writes so that a retry can never apply the same change twice.

Reference

Fields

Field-level violations

Each entry in errors describes one problem with one field:

Error codes

INVALID_ID, INVALID_KEY and INVALID_PARTS appear in results[].error.code of POST /v1/files/upload/multipart/complete/batch, not as a top-level error.

Legacy fields

Problem documents also carry three deprecated keys for integrations written before RFC 9457 errors: They will be removed in a future version. Migrate to detail, title and status.

When to retry

When you contact support@file.ai, include the requestId and code.

Idempotent requests

Retry writes safely, and which errors are replayed.

Pagination

Why a stale cursor returns 400.

Authentication and regions

API keys, read-only keys and base URLs.

Versioning and deprecation

How changes and deprecations are signalled.