> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error responses

> Every fileAI API error is an RFC 9457 problem document with a stable machine-readable code and a request correlation id.

## Overview

Every error response from the API is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)
problem document, served with `Content-Type: application/problem+json`.

```json theme={null}
{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/prod/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName"
    }
  ]
}
```

<Info>
  Branch your error handling on **`code`**, not on `detail` or `title`. `code` is
  a stable public contract — new codes may be added, but existing ones are never
  renamed or repurposed. `detail` is human-facing prose and can change at any
  time.
</Info>

## Fields

| Field      | Type   | Description                                                                              |
| ---------- | ------ | ---------------------------------------------------------------------------------------- |
| type       | string | URI identifying the problem type, e.g. `https://errors.file.ai/validation-failed`.       |
| title      | string | Stable, human-readable summary of the problem type.                                      |
| status     | number | HTTP status code, repeated in the body.                                                  |
| detail     | string | Human-readable explanation specific to this occurrence.                                  |
| instance   | string | URI reference for this occurrence — the full request path, including the `/prod` prefix. |
| code       | string | Stable machine-readable error code — branch on this.                                     |
| requestId  | string | Correlation id for the request. Quote it in support requests.                            |
| errors     | array  | Field-level violations. Populated on validation errors, `[]` otherwise.                  |
| retryAfter | number | Seconds until you may retry. Present on `429` only.                                      |

### Field-level violations

Each entry in `errors` describes one offending field:

| Field     | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| code      | string | Violation code, e.g. `REQUIRED`.                               |
| detail    | string | What was wrong, e.g. `must not be empty`.                      |
| pointer   | string | JSON Pointer to the offending body field, e.g. `#/fileName`.   |
| parameter | string | Name of the offending query or header parameter, e.g. `limit`. |

<Note>
  `pointer` is set for body fields and `parameter` for query/header parameters —
  an entry carries whichever one applies.
</Note>

## Error codes

| Code                             | Status | Title                          | When it happens                                                      |
| -------------------------------- | ------ | ------------------------------ | -------------------------------------------------------------------- |
| `BAD_REQUEST`                    | 400    | Bad request                    | The request could not be processed as sent.                          |
| `UNAUTHENTICATED`                | 401    | Unauthenticated                | The `x-api-key` header is missing or the key is invalid.             |
| `FORBIDDEN`                      | 403    | Forbidden                      | The key is inactive, or lacks access to the resource.                |
| `READONLY_KEY`                   | 403    | Read-only API key              | A read-only key was used on a write endpoint.                        |
| `NOT_FOUND`                      | 404    | Not found                      | The referenced resource does not exist in this workspace.            |
| `IDEMPOTENT_REQUEST_IN_PROGRESS` | 409    | Idempotent request in progress | An earlier request with the same `Idempotency-Key` is still running. |
| `VALIDATION_FAILED`              | 422    | Validation failed              | One or more parameters or body fields are invalid. See `errors[]`.   |
| `IDEMPOTENCY_KEY_REUSED`         | 422    | Idempotency key reused         | The same `Idempotency-Key` was reused with a different request body. |
| `RATE_LIMITED`                   | 429    | Too many requests              | The rate limit was exceeded. Wait `retryAfter` seconds.              |
| `INTERNAL_ERROR`                 | 500    | Internal server error          | Unexpected server-side failure. Safe to retry.                       |

## Legacy fields

Problem documents also carry three deprecated keys for backwards compatibility
with integrations written before RFC 9457 responses were introduced:

| Legacy field | Use instead        |
| ------------ | ------------------ |
| `message`    | `detail` / `title` |
| `error`      | `title`            |
| `statusCode` | `status`           |

<Warning>
  The legacy keys are deprecated and will be removed in a future version. Migrate
  to `detail`, `title`, and `status`.
</Warning>

## Handling errors

<AccordionGroup>
  <Accordion title="Retrying safely" icon="rotate">
    `429` and `500` are safe to retry. On `429`, wait `retryAfter` seconds; for
    `500`, back off exponentially. Send an
    [`Idempotency-Key`](/docs-api/api-idempotency) on write endpoints so a retry
    cannot apply the same change twice.
  </Accordion>

  <Accordion title="Do not retry" icon="ban">
    `400`, `401`, `403`, `404`, and `422` describe a problem with the request
    itself. Retrying without changing anything returns the same error.
  </Accordion>

  <Accordion title="Reporting a problem" icon="life-ring">
    Include the `requestId` and `code` when contacting
    [support@file.ai](mailto:support@file.ai) — `requestId` correlates your call
    to our server-side logs.
  </Accordion>
</AccordionGroup>