Troubleshooting

Find your symptom, apply the fix, and follow the link for details. When you contact support@file.ai, quote the X-Request-Id and the error code (Request ids).

Authentication and regions

Symptom	Fix	See
`401` on every request, with a key that works elsewhere	Send the key to the host of the region that issued it.	Regions
`401` `API key is missing`	Send the key in the `x-api-key` header.	Authentication
`400` asking for `x-project-id`	You are using a personal key: send the project id in `x-project-id`.	Key types
`403 READONLY_KEY` on a `POST`, `PATCH` or `DELETE`	Use a key with write permission.	What a key can do
`403` `API key is inactive.`	Create a new key, or ask a workspace admin to check it.	Create an API key
`403 FEATURE_DISABLED`	Ask your account manager or support to enable the feature for your workspace; retrying won’t help.	Error codes

Uploads

Symptom	Fix	See
The `PUT` to the presigned URL fails	Request a new URL and `PUT` within 300 seconds, with the same `Content-Type` as `fileType`.	Uploads
`422` `OCR model '…' has been retired.`	Omit `ocrModel` to use the project default, or pick a current model.	Retired models
Upload accepted, but the file is never processed	Check `GET /v1/uploads/{uploadId}` for a `processing_failed` step and its `errorReason`, and check the file’s type and size are supported.	Supported file types
`422 INVALID_BATCH`, `BATCH_TOO_LARGE` or `BATCH_PARTS_TOO_LARGE`	Split the batch, or raise `partSizeLimit` for a multipart batch.	Batch registration
`422` when you send `enabledProducts`	Use the single upload route, check the product and `storageOnly` combination, and ask support whether the products are enabled for your workspace.	Upload options

Extraction

Symptom	Fix	See
`413` or `415` from `/extract`, `/split` or `/classify`	Send a supported type, declared correctly, under the size limit; otherwise use a stored upload.	Request
A table stops at 100 rows	Add `includeFullTableData=true` to `GET /v1/files/{fileId}/values`.	Tables
A number or table cell is `null` where the file shows `0`	Expected: values of `0` come back as `null`. Handle `null` in number fields.	How values come back
A retried `/extract` created a second job	Send a `client_ref` and discard duplicates on your side; these endpoints ignore `Idempotency-Key`.	Accepted but ignored

Callbacks and jobs

Symptom	Fix	See
The callback never arrived	Poll as a fallback: callbacks are sent once and never retried.	Polling or callbacks
No callback for an extract, split or classify job	Send `callback_url` on the request; the API key’s default URL is not used for these jobs.	Document jobs
`fileIds` in the callback isn’t an array	Split the string on `,`.	Payload fields
`statuses` in `GET /v1/uploads/{uploadId}` is empty	Read each document’s `status` in `files` instead; steps are kept for 10 minutes.	Uploads
A forensics run stays `queued` or `running`	Retry it, then poll the new `run_id` the retry returns.	Forensics runs

Pagination and retries

Symptom	Fix	See
`400` `Please restart pagination` with a cursor	Start a new walk with an empty `cursor`, and keep filters and sort fixed until `hasMore` is `false`.	Cursor mode
Legacy pages overlap or skip rows	Send both `sortBy` and `sortOrder`, or switch to cursor mode.	Legacy mode
`409 IDEMPOTENT_REQUEST_IN_PROGRESS`	Wait, then retry with the same key and body.	Outcomes
`422 IDEMPOTENCY_KEY_REUSED`	Use a new key for every new operation.	Outcomes
The same error comes back after you fixed the request	Send the corrected request with a new `Idempotency-Key`.	Which errors are cached
`429 RATE_LIMITED`	Wait `Retry-After` seconds, then retry.	Rate limits

MCP

Symptom	Fix	See
`400` asking for the project id, after signing in	Call `list_projects`, then pass the id as `project_id` to the other tools.	MCP tools
`403` `You do not have access to this project.`	Use an id from `list_projects`, or reconnect and include that workspace.	Choosing a project
`project_id` is rejected as invalid	Pass the 24-character id from `list_projects`, not the project name.	MCP tools

Still stuck?

Email support@file.ai with the X-Request-Id (or requestId), the error code, the endpoint and the time of the request.

Errors

Every error code and when to retry.

Async jobs

Polling uploads, jobs and forensics runs.

Production checklist

What to set up before you go live.

Authentication and regions

Keys, hosts and request conventions.

Get started

Products

Build

Go live

Authentication and regions

Uploads

Extraction

Callbacks and jobs

MCP

Still stuck?

Errors

Async jobs

Production checklist

Authentication and regions

​Authentication and regions

​Uploads

​Extraction

​Callbacks and jobs

​Pagination and retries

​MCP

​Still stuck?

​Related

Errors

Async jobs

Production checklist

Authentication and regions

Authentication and regions

Uploads

Extraction

Callbacks and jobs

Pagination and retries

MCP

Still stuck?

Related