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

# Errors

> The format of every error, every error code with its cause and what to do, and the rules for retrying.

This page is the reference for errors. After you read it, you can read any error response, find its cause in the table, and know whether to correct the request or to wait and try again.

## The format of an error

Every error response has the same three fields:

```json theme={null}
{
  "error": "agent agent_01J... is still initializing",
  "code": "agent_not_ready",
  "request_id": "req_01J..."
}
```

| Field | Meaning |
| - | - |
| `error` | A sentence for a person. The wording can change. |
| `code` | A fixed name for the condition. Write your code against this field. |
| `request_id` | Send this to support when you report a problem. |

Make decisions in your code on `code`, not on the HTTP status. Two different errors can have the same status and need different handling.

## Two errors that any call can return

* `401 unauthorized`: your key is missing, unknown, revoked, or expired. Check the key.
* `503 service_unavailable`: a part of Priors did not respond, or an agent is restarting after a restart of the service. The `error` text says which. Wait a few seconds, then send the same request again.

The tables on the other pages leave these two out.

## Every error code

The table below lists every code, its status, its cause, and what to do.

| `code` | Status | Cause | What to do |
| - | - | - | - |
| `invalid_request` | `400` or `422` | The body or a parameter has the wrong format, or a value is outside its allowed range. `422` comes from schema validation. `400` comes from a rule that the schema cannot express. Handle both the same way. | Read `error`. Correct the request. Do not send the same request again. |
| `unauthorized` | `401` | The key is missing, malformed, unknown, revoked, or expired. All five answer alike on purpose. | Check the key. Quote the key id when you contact us: that is how we tell the five apart for you. |
| `forbidden` | `403` | The credential is valid but may not take this action. | Read `error`. |
| `payment_required` | `402` | Your organization is out of credit. Nothing was learned, and nothing was answered. | Add credits. See [Credits](/docs/credits). |
| `not_found` | `404` | The id does not exist, or your key does not reach it. | Check the id, and check that the agent belongs to your organization. |
| `agent_not_found` | `404` | The same as `not_found`, for an agent. | Check the `agent_id`. |
| `thread_not_found` | `404` | The same as `not_found`, for a thread. | Check the `thread_id`. |
| `conflict` | `409` | The request does not fit the current state. Sending it again without a change does not help. | Read `error`. Change the request. |
| `agent_not_ready` | `409` | The agent is still `initializing`, or it `failed`. | Poll `GET /v1/agents/{agent_id}` until `status` is `ready`. If it is `failed`, delete the agent and create a new one. |
| `agent_quota_exceeded` | `409` | Your organization has reached its limit of 100 agents. | Delete an agent you no longer need, or contact us. |
| `upload_in_progress` | `409` | No longer sent. A file sent while the agent reads another is accepted with `queued: true`. Older clients may still handle it. | Wait `Retry-After` seconds, then try again. |
| `duplicate_upload_in_progress` | `409` | This agent is already learning **this** file, or has it queued in another thread. | Do nothing. What it learns is searchable from every thread of the agent. |
| `document_already_ingested` | `409` | This agent already read these exact bytes in another thread. Nothing is running, and waiting does not help. | The memories are already searchable from here. To read the file again anyway, and store a second copy, send `allow_duplicate=true`. |
| `document_uploaded_elsewhere` | `409` | An upload of this file in another thread stopped partway or failed. | Finish it with `POST .../sources/{source_id}/finish-learning`, which charges only what is left. Or send `allow_duplicate=true` to read the whole file again here, charged in full. |
| `payload_too_large` | `413` | An image is larger than 10 MB, a chat message names more than 10 images, or its images total more than 32 MB. | Send a smaller image, or fewer images. |
| `document_too_large` | `413` | The document is larger than the size limit. | Split the document. |
| `document_too_complex` | `413` | The document is under the size limit, but processing it passes a limit: the converter's resource limit, the page limit of text recognition for a scan, or its request size limit. `error` says which. | Split the document, or send a version with text instead of a scan. |
| `document_too_many_turns` | `413` | The document splits into more than 2,000 pieces. | Split the document, or raise `max_chars`. |
| `document_too_many_pages` | `413` | The document has more pages than text recognition accepts in one upload. | Split the document. |
| `document_too_large_for_ocr` | `413` | A scanned document is larger than text recognition accepts. | Split it, or send a version with text. |
| `unsupported_document` | `400` | Priors does not convert this file type. | Convert the file to PDF or another supported format. |
| `empty_document` | `400` | The document contains no readable text. | Check the file. |
| `encrypted_document` | `400` | The document has a password. | Remove the password, then try again. |
| `malformed_document` | `400` | The file could not be read. | Export the file again, then try again. |
| `document_needs_ocr` | `400` | The document is a scan, and text recognition is not available for it. | Send a version with text. |
| `ingestion_failed` | `400` | The conversion failed for a reason that no other document code names. | Read `error`. Export the file again. |
| `document_service_unavailable` | `502` | The document converter did not respond. The file is fine. | Wait, then upload the same file again. |
| `ocr_failed` | `502` | Text recognition failed on a scan. | Wait, then try again. If it fails again, send a version with text. |
| `document_pages_unexpected` | `502` | Text recognition returned pages that do not belong to the document. Nothing was stored. | Wait, then try again. |
| `ocr_busy` | `503` | Text recognition is busy with other uploads. | Try again in a few minutes. |
| `rate_limit_exceeded` | `429` | Too many requests in a time window, or this agent is already learning something (`Retry-After: 1`). `details` names which control refused. | Wait the number of seconds in `Retry-After`, then send the request again. |
| `service_unavailable` | `503` | A part of Priors did not respond. | Wait, then try again. The request can succeed later. |
| `answer_model_unavailable` | `503` | The model that writes answers did not respond. | Wait, then try again. |
| `service_not_configured` | `503` | A feature is not switched on for your organization. | Trying again does not help. Contact us. |
| `internal_error` | `500` | A defect on our side. | Trying again does not help. Contact us with the `request_id`. |

## Rate limit headers

When a request hits a limit, the response is `429` and has these headers:

| Header | Meaning |
| - | - |
| `Retry-After` | The number of seconds to wait before you try again. |
| `X-RateLimit-Reset` | The same moment, as a Unix timestamp. |

Wait at least `Retry-After` seconds. Do not try again in a tight loop.

## Rules for trying again

1. For `5xx` with `service_unavailable`, `answer_model_unavailable`, `document_service_unavailable`, `ocr_failed`, `document_pages_unexpected`, or `ocr_busy`: wait, then try again. Double the wait after each failure, starting at one second. For `ocr_busy`, start at one minute. Stop after five tries.
2. For `429`: wait `Retry-After` seconds, then try again.
3. For `409` with `agent_not_ready`: poll the agent, then try again when its status is `ready`.
4. For every other `4xx`: do not try again. Correct the request.
5. For `500` and `service_not_configured`: do not try again. Contact us with the `request_id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.