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
`plan_limit`	`403`	Your plan has no room for one more of this	Do not retry. See Plan and usage
`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
`model_key_missing`	`409`	Your plan answers on your own AI keys and none fits this model	Save a key. See Your own AI keys
`model_key_rejected`	`424`	The AI provider refused your own key	Replace the key, then retry
`rate_limit_exceeded`	`429`	Over the rate limit	Wait for `Retry-After`, then retry
`quota_exceeded`	`429`	Your organisation’s monthly answer allowance is used	Do not retry. See below
`budget_exceeded`	`429`	Your organisation’s hard monthly AI budget is spent	Do not retry. See AI gateway controls
`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.

The monthly answer limit

Two different refusals arrive as 429, and they need different handling. Branch on code, not on the status.

rate_limit_exceeded means too many requests in the last minute. Wait for Retry-After, then retry.
quota_exceeded means your organisation has used its monthly answer allowance. Retrying does not help: Retry-After is the number of seconds until the next calendar month begins, which can be weeks.

{
  "code": "quota_exceeded",
  "message": "The monthly answer limit for this account has been reached."
}

Only a request that asks a question can be refused this way: sending a message, the streaming form of the same request, and the ask_assistant MCP tool. The refusal comes before the question is stored and before any model is called, and for a streaming request it arrives as a 429 status, not as an event on an open stream. Read Get answer allowance to see how close you are before you reach it.

Email, invitations and password reset

Sending an invitation, re-sending one and asking for a password reset all send email, so they can fail in ways other requests cannot.

Situation	`code`	HTTP	What to do
The deployment has no email provider set up	`dependency_failure`	`503`	Retrying does not help. Ask the operator of your deployment to set up email
The email provider refused the message or could not be reached	`provider_failure`	`502`	Retry in a few minutes
More than 30 invitations from one organisation in an hour	`rate_limit_exceeded`	`429`	Wait, then retry
An invitation or reset link that was used, expired or replaced	`not_found`	`404`	Ask for a new link. Every unusable link gives the same answer, whatever the reason

The 503 arrives before anything is written, so no invitation is created that nobody could receive.

{
  "code": "dependency_failure",
  "message": "This deployment cannot send e-mail yet."
}

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
Saving a connection with a name already in use, or past the limit of 100 connections	Choose another name, or delete a connection you no longer use
Deleting a connection that a source still uses	Remove the sources the message names, then delete it
Inviting an address that already has an open invitation	Re-send the existing one
Inviting someone who is already a member	Nothing to do; change their role if needed
Revoking an invitation that was already accepted	Remove the member instead

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. Do not retry a 429 whose code is quota_exceeded.
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.

Last modified on November 12, 2026

Get started

Conversations

Assistants

Models

Knowledge

Widget deployments

Widget (public)

MCP

Connections

Slack

Microsoft Teams

API keys

Members

Invitations

Analytics

Support access

Audit log

AI search visibility

AI employees

Branding

Operations

API error codes and how to handle them

Error codes

The monthly answer limit

Email, invitations and password reset

Not found, not forbidden

Common conflicts

Errors during streaming

Retrying safely

​Error codes

​The monthly answer limit

​Email, invitations and password reset

​Not found, not forbidden

​Common conflicts

​Errors during streaming

​Retrying safely

Error codes

The monthly answer limit

Email, invitations and password reset

Not found, not forbidden

Common conflicts

Errors during streaming

Retrying safely