API error codes and how to handle them

Every error has the same body, with exactly two fields:

{
  "code": "validation_error",
  "message": "'text' is required."
}

code is stable and machine-readable. Branch on it.
message is for people and may be reworded. Do not parse it.

Errors never contain stack traces, internal identifiers or configuration.

Error codes

`code`	HTTP	Meaning	What to do
`validation_error`	`400`	The request is malformed, or a field is missing or out of range	Fix the request. Do not retry it unchanged
`authentication_error`	`401`	No usable credential	Check the API key, then retry
`authorization_error`	`403`	Authenticated, but not permitted	Do not retry. Use a key or account with the right role
`not_found`	`404`	No such resource in your organisation	Do not retry
`conflict`	`409`	The request conflicts with the current state	Re-read the resource, then decide
`rate_limit_exceeded`	`429`	Over the rate limit	Wait for `Retry-After`, then retry
`internal_error`	`500`	Unexpected failure	Retry once with backoff, then contact your MITHUNAI representative
`provider_failure`	`502`	The model provider failed	Retry with backoff
`dependency_failure`	`503`	A required service is unavailable	Retry with backoff
`retrieval_failure`	`503`	Retrieval could not complete	Retry with backoff

These codes will not be renamed within v1.

Not found, not forbidden

A 404 means “no such resource that you can see”. A resource in another organisation returns the same 404 as one that does not exist, so identifiers cannot be used to discover what exists elsewhere. A request to a path or method that does not exist at all is answered by the web server’s own 404 or 405, which may not have a JSON body.

Common conflicts

Situation	Resolution
Asking a question while the conversation is still answering the previous one	Wait for the first turn to finish, or use another conversation
Saving branding or an assistant with a stale `revision`	Read the current version and retry
Creating or renaming a collection or widget embed, or creating an API key, with a name already in use	Choose another name

Errors during streaming

Once a stream has started, the HTTP status is already 200. A failure after that point arrives as a final answer.error event carrying the same code and message. Always read the final event. See Streaming.

Retrying safely

Retry only 429, 500, 502 and 503, with exponential backoff and jitter.
Honour Retry-After when present; it is omitted when no wait is known.
When retrying a question, send the same idempotency_key so a request that actually succeeded is not asked, and paid for, twice.

Get started

Conversations

Assistants

Models

Knowledge

Widget deployments

Widget (public)

MCP

API keys

Members

Analytics

Support access

Branding

Operations

API error codes and how to handle them

Error codes

Not found, not forbidden

Common conflicts

Errors during streaming

Retrying safely

​Error codes

​Not found, not forbidden

​Common conflicts

​Errors during streaming

​Retrying safely

Error codes

Not found, not forbidden

Common conflicts

Errors during streaming

Retrying safely