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
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 anX-Request-Id header, and errors repeat it as requestId. fileAI picks it in this order:
- The
X-Request-Idheader you sent, if any — so you can use your own correlation ids. - The trace id from a W3C
traceparentheader, if you sent a valid one. - A newly generated id.
Rate limits
A429 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
Idempotency-Key on writes so that a retry can never apply the same change twice.
Reference
Fields
Field-level violations
Each entry inerrors 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.
Related
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.