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

# Error Reference

> Common TrueParser API errors and what they mean.

## Overview

TrueParser returns standard HTTP status codes together with JSON error bodies for most API failures.

The most common error payload shape is:

```json theme={null}
{
  "error": "error_code",
  "message": "Human-readable explanation"
}
```

Some endpoints may also return route-specific fields such as `detail`.

## Authentication Errors

These errors happen when a request is missing a valid access token or the token does not satisfy API policy.

| HTTP Status | Error Code           | Meaning                                                    |
| ----------- | -------------------- | ---------------------------------------------------------- |
| `401`       | `missing_token`      | No bearer token was provided.                              |
| `401`       | `token_expired`      | The access token has expired.                              |
| `401`       | `invalid_token`      | The token could not be accepted.                           |
| `403`       | `invalid_scope`      | The token does not have the required API scope.            |
| `403`       | `domain_not_allowed` | The request origin is not allowed for this application.    |
| `503`       | `auth_unavailable`   | Authentication infrastructure was temporarily unavailable. |

## Document Submission Errors

These errors happen during document ingestion.

| HTTP Status | Error Code                        | Meaning                                                                              |
| ----------- | --------------------------------- | ------------------------------------------------------------------------------------ |
| `400`       | `invalid_input`                   | The uploaded file is missing or empty.                                               |
| `400`       | `document_type_required`          | ZIP uploads must include an explicit `documentType`.                                 |
| `400`       | `unsupported_format`              | The file format is not supported.                                                    |
| `400`       | `csv_route_required`              | CSV uploads must include `csvRoute`.                                                 |
| `400`       | `sql_dialect_required`            | SQL uploads must include `sqlDialect`.                                               |
| `400`       | `pdf_mode_required`               | PDF uploads must include `pdfMode`.                                                  |
| `400`       | `invalid_metadata`                | `customMetadataJson` is not valid JSON.                                              |
| `403`       | `advanced_extraction_not_allowed` | The current plan does not allow advanced PDF extraction.                             |
| `403`       | `license_restriction`             | The requested operation is not allowed under the current plan or format entitlement. |
| `413`       | `document_too_large`              | The upload exceeds the maximum allowed size for the plan.                            |
| `429`       | `rate_limit_exceeded`             | The application exceeded its API traffic limit.                                      |
| `429`       | `quota_exceeded`                  | The application exceeded a quota window and cannot accept more work right now.       |
| `503`       | none fixed                        | The node is temporarily overloaded.                                                  |

## Result and Status Errors

These errors happen when checking status or retrieving parsed results.

| HTTP Status | Error Code          | Meaning                                                      |
| ----------- | ------------------- | ------------------------------------------------------------ |
| `404`       | `not_found`         | No job exists for the requested document id.                 |
| `404`       | `result_not_found`  | The job completed but no result reference was available.     |
| `404`       | `document_expired`  | The parsed result is no longer available.                    |
| `422`       | `extraction_failed` | The parser failed to process the document.                   |
| `202`       | none fixed          | The job is still processing and the result is not ready yet. |

## Health and Overload Responses

TrueParser also exposes health and overload signals:

| Endpoint             | HTTP Status | Meaning                                                    |
| -------------------- | ----------- | ---------------------------------------------------------- |
| `/health/live`       | `200`       | The service process is alive.                              |
| `/health/ready`      | `503`       | A required dependency is not ready.                        |
| `/health/node-state` | `503`       | The node is overloaded and should not receive new traffic. |

When a node is overloaded, the API may return a response like:

```json theme={null}
{
  "status": 503,
  "state": "overloaded",
  "reason": "cpu",
  "retryAfter": 60
}
```

## Quota and Processing Failures

Background processing failures may eventually surface through status polling or result retrieval.

Common examples include:

* `quota_exceeded`
* `document_quota_exceeded`
* `job_timeout`
* `processing_failed`
* `transient_infrastructure_failure`

## What Clients Should Do

* treat the HTTP status code as the primary signal
* inspect the `error` field when present
* use retry with backoff for `429` and appropriate `503` responses
* poll status for asynchronous jobs instead of assuming immediate completion