Errors

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:

{
  "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.
`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

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.
For 429: wait Retry-After seconds, then try again.
For 409 with agent_not_ready: poll the agent, then try again when its status is ready.
For every other 4xx: do not try again. Correct the request.
For 500 and service_not_configured: do not try again. Contact us with the request_id.

Start here

Walkthroughs

How Priors works

Reference

The format of an error

Two errors that any call can return

Every error code

Rate limit headers

Rules for trying again

​The format of an error

​Two errors that any call can return

​Every error code

​Rate limit headers

​Rules for trying again

The format of an error

Two errors that any call can return

Every error code

Rate limit headers

Rules for trying again