Errors

Every non-2xx response uses one consistent JSON shape, so clients can handle failures uniformly.

Error schema

Errors carry a single human-readable error string. Rate-limit responses (429) add retryAfter and limit.

{ "error": "Collection not found" }

Code	Meaning	Common cause	How to fix
`400`	Bad Request	Malformed JSON, or a field failed validation (e.g. empty query).	Check the request body against the endpoint schema.
`401`	Unauthorized	Missing, invalid, expired, or revoked credential — or an API key on a session-only endpoint.	Send a valid bearer token of the accepted type.
`404`	Not Found	The resource does not exist, or belongs to another tenant (never disclosed).	Verify the id and that it belongs to your tenant.
`409`	Conflict	The action conflicts with current state (querying a collection with no ready documents; re-ingesting one already processing).	Wait for ingestion to finish, then retry.
`413`	Payload Too Large	An upload exceeded the 25 MB limit.	Split or compress the file.
`415`	Unsupported Media Type	The uploaded file is not PDF, plain text, or Markdown.	Convert to a supported format before uploading.
`422`	Unprocessable Entity	A query found no relevant content in the collection.	Rephrase, or confirm the relevant document is ingested.
`429`	Too Many Requests	The API key exceeded its rate limit.	Back off using Retry-After (see rate limits).
`500`	Internal Server Error	An unexpected server-side failure.	Retry with backoff; if it persists, report it.

The API reference lists exactly which of these each endpoint can return.