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

# API error codes and how to handle them

> Every MITHUNAI error carries a code and a message. Each code, the HTTP status it arrives with, what causes it, and what your client should do in response to it.

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/api-reference/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.