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

# Errors

> Read LLM API errors, handle both error shapes in your code, and decide when to retry.

Early access
**Gnani Evon v3.5** is now available as an API to early access registrants.

## Two error shapes

An error response has an HTTP error status and a JSON body. The body comes in one of two shapes, depending on where the request was refused:

| | LLM API errors | Gateway errors |
| - | - | - |
| **Returned for** | Bad requests, safety refusals, the daily token quota, model and server errors | Authentication, key scope, request rate and the daily token quota |
| **Top-level key** | `error` | `detail` |
| **Code field** | `error.code`, lower case (`invalid_request`) | `detail.error_code`, upper case (`RATE_LIMITED`) |
| **Message field** | `error.message` | `detail.message` |

```json LLM API error wrap theme={null}
{
  "error": {
    "message": "temperature must be between 0 and 2, got -1",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}
```

```json Gateway error wrap theme={null}
{
  "detail": {
    "error_code": "RATE_LIMITED",
    "message": "Request rate exceeded: at most 60 requests per minute.",
    "status_code": 429
  }
}
```

Both use the same HTTP status codes as OpenAI, so the OpenAI SDKs raise their usual exceptions for both. Branch on the HTTP status and the code, not on `message`: the message is for people and may change.

> [!NOTE]
>
> **The daily token quota has two codes.** `DAILY_TOKEN_QUOTA_EXCEEDED` comes from the gateway, in the `detail` shape. `daily_token_quota_exceeded` comes from the API, in the `error` shape. Both mean the quota is used up until midnight IST. Check for both.

***

## Handle errors in code

Read the code from whichever shape the response uses:

```python Python (OpenAI SDK) theme={null}
import os
import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.vachana.ai/v1",
    api_key=os.environ["GNANI_API_KEY"],
)

try:
    completion = client.chat.completions.create(
        model="evon-v3.5",
        messages=[{"role": "user", "content": "What is UPI?"}],
    )
    print(completion.choices[0].message.content)
except openai.APIStatusError as e:
    body = e.body if isinstance(e.body, dict) else {}
    # LLM errors use "error"; gateway errors use "detail".
    # The Python SDK may already have unwrapped "error", so fall back to the body itself.
    err = body.get("error") or body.get("detail") or body
    code = err.get("code") or err.get("error_code")
    print(e.status_code, code, err.get("message"))
except openai.APIConnectionError:
    print("Could not reach the API. Retry with backoff.")
```

```python Python (Gnani SDK) theme={null}
# pip install "gnani-vachana[llm]"
import openai
from gnani.llm import GnaniLLMClient

client = GnaniLLMClient()  # AsyncGnaniLLMClient raises the same exceptions; await the call

try:
    completion = client.chat.completions.create(
        model="evon-v3.5",
        messages=[{"role": "user", "content": "What is UPI?"}],
    )
    print(completion.choices[0].message.content)
except openai.APIStatusError as e:
    # e.code is the error code, for example "invalid_request" or "invalid_api_key"
    print(e.status_code, e.code, e.message)
except openai.APIConnectionError:
    print("Could not reach the API. Retry with backoff.")
```

```javascript JavaScript (OpenAI SDK) theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.vachana.ai/v1",
  apiKey: process.env.GNANI_API_KEY,
});

try {
  const completion = await client.chat.completions.create({
    model: "evon-v3.5",
    messages: [{ role: "user", content: "What is UPI?" }],
  });
  console.log(completion.choices[0].message.content);
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    // LLM errors use "error"; gateway errors use "detail".
    const body = err.error ?? {};
    const info = body.detail ?? body;
    const code = info.code ?? info.error_code;
    // If no code is available, branch on err.status (401, 403, 429).
    console.error(err.status, code, info.message ?? err.message);
  } else {
    throw err;
  }
}
```

```python Python (requests) theme={null}
import os
import requests

response = requests.post(
    "https://api.vachana.ai/v1/chat/completions",
    headers={"X-API-Key-ID": os.environ["GNANI_API_KEY"]},
    json={"model": "evon-v3.5", "messages": [{"role": "user", "content": "What is UPI?"}]},
    timeout=120,
)

body = response.json()
if response.ok:
    print(body["choices"][0]["message"]["content"])
else:
    # LLM errors use {"error": {...}}; authentication and rate-limit errors use {"detail": {...}}
    error = body.get("error") or body.get("detail") or {}
    print(response.status_code, error.get("code") or error.get("error_code"), error.get("message"))
```

***

## Error codes

LLM errors use OpenAI's error format, so the OpenAI SDKs raise them as their usual exceptions (`BadRequestError`, `RateLimitError` and so on):

```json theme={null}
{
  "error": {
    "message": "temperature must be between 0 and 2, got -1",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}
```

Use the HTTP status and `error.code` in your code. `message` explains the problem in plain words and may change.

| HTTP | `error.code` | What it means | What to do |
| - | - | - | - |
| `400` | `invalid_request` | The body is not valid JSON, or a field is missing, has the wrong type or is out of range. The message names the field, for example `messages[0].content is required`. | Fix the request. Retrying it unchanged fails again. |
| `400` | `context_length_exceeded` | The conversation is too long, or the conversation plus `max_tokens` does not fit in the context. See [Limits](https://docs.gnani.ai/api/LLM/limits.md). | Remove older messages, shorten the text, or lower `max_tokens`. |
| `400` | `content_filter` | The safety filters refused the request. See [Safety and privacy](https://docs.gnani.ai/api/LLM/safety.md). | Change the request. Retrying it unchanged fails again. |
| `400` | `model_rejected_request` | The model could not accept the request as sent. The message says why. | Fix the request. |
| `404` | `model_not_found` | `model` is not a model this API serves. | Send `evon-v3.5`, or leave out `model`. |
| `413` | `request_too_large` | The body is over 10 MB, or the messages hold more than 1 MB of text. | Send less text. |
| `429` | `daily_token_quota_exceeded` | Your daily token quota is used up. | Wait until it resets at midnight IST. `Retry-After` gives the seconds left. |
| `429` | `web_search_limit_exceeded` | You have used today's [web searches](https://docs.gnani.ai/api/LLM/web-search.md). | Send the request without the `web_search` tool, or wait until midnight IST. |
| `429` | `model_overloaded` | The model is busy. | Retry with backoff. |
| `500` | `internal_error` | Something went wrong on our side. | Retry with backoff. |
| `502` | `upstream_error` | The model could not be reached or could not serve the request. | Retry with backoff. |
| `503` | `guardrail_unavailable` | The safety check could not run, so the request was not sent to the model. | Retry with backoff. |
| `503` | `web_search_unavailable` | Web search is not available right now. | Retry later, or send the request without the `web_search` tool. |
| `504` | `upstream_timeout` | The model did not finish within the time limit. | Retry. If it keeps happening, ask for a shorter reply (lower `max_tokens`) or turn [thinking](https://docs.gnani.ai/api/LLM/thinking.md) off. |

**Authentication and request-rate errors come from the API gateway and use a different shape.** The OpenAI SDKs still raise them by status (`AuthenticationError`, `PermissionDeniedError`, `RateLimitError`):

```json theme={null}
{"detail": {"error_code": "RATE_LIMITED", "message": "Request rate exceeded: at most 60 requests per minute.", "status_code": 429}}
```

| HTTP | `detail.error_code` | What it means | What to do |
| - | - | - | - |
| `401` | `MISSING_API_KEY` | No API key was sent. | Send the key in `X-API-Key-ID` or `Authorization: Bearer`. |
| `401` | `INVALID_API_KEY` | The key is not valid. | Check the key. |
| `403` | `SCOPE_NOT_ALLOWED` | The key does not have access to the LLM API (`Service 'LLM' not in allowed scopes`). | Use a key with LLM access. |
| `429` | `RATE_LIMITED` | Too many requests per second or per minute, or a request is still running and your plan allows one at a time. | Wait, then retry with backoff. Honour `Retry-After` when it is sent. |
| `429` | `DAILY_TOKEN_QUOTA_EXCEEDED` | Your daily token quota is already used up. | Wait until midnight IST (`Retry-After`). |

Errors that happen after a stream has started arrive as a last event in the stream. See [Streaming](https://docs.gnani.ai/api/LLM/streaming.md#errors).

The codes for every Gnani API are in the [Error Reference](https://docs.gnani.ai/api/introduction/errors.md).

***

## Retrying

Retry connection errors and `429`, `500`, `502`, `503` and `504` with exponential backoff, for example 1 s, 2 s, then 4 s. When a response has `Retry-After`, wait at least that long. Do not retry other `4xx` errors: they fail the same way until you change the request.

OpenAI's SDKs, and the Gnani Python SDK clients built on them, already retry these for you (2 retries by default; set `max_retries` on the client to change it).

### Retry guide by status

| HTTP | Code | Retry? |
| - | - | - |
| `400` | `invalid_request`, `context_length_exceeded`, `content_filter`, `model_rejected_request` | No. Change the request first. |
| `401` | `MISSING_API_KEY`, `INVALID_API_KEY` | No. Fix the key. |
| `403` | `SCOPE_NOT_ALLOWED` | No. Use a key with LLM access. |
| `404` | `model_not_found` | No. Fix `model`. |
| `413` | `request_too_large` | No. Send less text. |
| `429` | `RATE_LIMITED`, `model_overloaded` | Yes, with backoff. Honour `Retry-After` when it is sent. |
| `429` | `DAILY_TOKEN_QUOTA_EXCEEDED`, `daily_token_quota_exceeded` | Not until the quota resets at midnight IST. `Retry-After` gives the seconds left. |
| `429` | `web_search_limit_exceeded` | Not with the `web_search` tool until midnight IST. You can send the request without the tool. |
| `500` | `internal_error` | Yes, with backoff. |
| `502` | `upstream_error` | Yes, with backoff. |
| `503` | `guardrail_unavailable` | Yes, with backoff. |
| `503` | `web_search_unavailable` | Yes, later, or send the request without the `web_search` tool. |
| `504` | `upstream_timeout` | Yes. If it keeps happening, lower `max_tokens` or turn [thinking](https://docs.gnani.ai/api/LLM/thinking.md) off. |

> [!TIP]
>
> An SDK retry of a daily-quota `429` fails again until the reset. To stop retrying it, check the code and skip it in your own retry logic, or set `max_retries` to `0` and retry yourself.

## Related

> [card] [Limits](https://docs.gnani.ai/api/LLM/limits.md)
>
> Rate limits and the daily token quota behind most `429` errors.

> [card] [Error Reference](https://docs.gnani.ai/api/introduction/errors.md)
>
> Error formats and codes for every Gnani API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.