# Troubleshooting Source: https://docs.file.ai/api/troubleshooting > Find the cause and fix for common fileAI API failures, from 401s to missing callbacks. Production # Troubleshooting Copy pageCopy page Find the cause and fix for common fileAI API failures, from 401s to missing callbacks. Copy pageCopy page Find your symptom, apply the fix, and follow the link for details. When you contact [support@file.ai](mailto:support@file.ai), **quote the `X-Request-Id`** and the error `code` ([Request ids](/api/errors#request-ids)). ## [​ ](#authentication-and-regions) 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](/authentication#regions) `401` `API key is missing` Send the key in the `x-api-key` header. [Authentication](/authentication#authenticate-a-request) `400` asking for `x-project-id` You are using a personal key: send the project id in `x-project-id`. [Key types](/authentication#key-types) `403 READONLY_KEY` on a `POST`, `PATCH` or `DELETE` Use a key with write permission. [What a key can do](/authentication#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](/authentication#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](/api/errors#error-codes) ## [​ ](#uploads) 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](/ingest/uploads) `422` `OCR model '…' has been retired.` Omit `ocrModel` to use the project default, or pick a current model. [Retired models](/ingest/ocr-models#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](/ingest/supported-files) `422 INVALID_BATCH`, `BATCH_TOO_LARGE` or `BATCH_PARTS_TOO_LARGE` Split the batch, or raise `partSizeLimit` for a multipart batch. [Batch registration](/ingest/uploads#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](/ingest/uploads#upload-options) ## [​ ](#extraction) 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](/extract/split-classify#request) A table stops at 100 rows Add `includeFullTableData=true` to `GET /v1/files/{fileId}/values`. [Tables](/extract/data-types#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](/extract/data-types#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](/api/idempotency#accepted-but-ignored) ## [​ ](#callbacks-and-jobs) Callbacks and jobs Symptom Fix See The callback never arrived Poll as a fallback: callbacks are sent once and never retried. [Polling or callbacks](/api/async-jobs#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](/api/async-jobs#document-jobs) `fileIds` in the callback isn’t an array Split the string on `,`. [Payload fields](/deliver/callbacks#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](/api/async-jobs#uploads) A forensics run stays `queued` or `running` Retry it, then poll the **new** `run_id` the retry returns. [Forensics runs](/api/async-jobs#forensics-runs) ## [​ ](#pagination-and-retries) 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](/api/pagination#cursor-mode) Legacy pages overlap or skip rows Send both `sortBy` and `sortOrder`, or switch to cursor mode. [Legacy mode](/api/pagination#legacy-mode) `409 IDEMPOTENT_REQUEST_IN_PROGRESS` Wait, then retry with the same key and body. [Outcomes](/api/idempotency#outcomes) `422 IDEMPOTENCY_KEY_REUSED` Use a new key for every new operation. [Outcomes](/api/idempotency#outcomes) The same error comes back after you fixed the request Send the corrected request with a **new** `Idempotency-Key`. [Which errors are cached](/api/idempotency#which-errors-are-cached) `429 RATE_LIMITED` Wait `Retry-After` seconds, then retry. [Rate limits](/api/rate-limits) ## [​ ](#mcp) 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](/mcp/tools#parameters-every-tool-shares) `403` `You do not have access to this project.` Use an id from `list_projects`, or reconnect and include that workspace. [Choosing a project](/mcp/overview#choosing-a-project) `project_id` is rejected as invalid Pass the 24-character id from `list_projects`, not the project name. [MCP tools](/mcp/tools#parameters-every-tool-shares) ## [​ ](#still-stuck) Still stuck? Email [support@file.ai](mailto:support@file.ai) with the `X-Request-Id` (or `requestId`), the error `code`, the endpoint and the time of the request. ## [​ ](#related) Related ## 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. [Previous](/api/versioning)[ Workspace Sign up, invite your team, assign roles and create API keys. Next ](/account/workspace-setup) ⌘I ## On this page * [Authentication and regions](#authentication-and-regions) * [Uploads](#uploads) * [Extraction](#extraction) * [Callbacks and jobs](#callbacks-and-jobs) * [Pagination and retries](#pagination-and-retries) * [MCP](#mcp) * [Still stuck?](#still-stuck) * [Related](#related)