# Errors

> Every HTTP status the 7API API returns (400, 401, 402, 403, 404, 413, 415, 429, 5xx), what each means and whether to retry, with the JSON error shapes for OpenAI and Anthropic clients.


Errors come back as JSON with an HTTP status code. The `error.type` and `error.message` fields are always present.

```json
{ "error": { "type": "insufficient_balance", "message": "Out of balance. Top up via the Telegram bot." } }
```

When the failure happened at an upstream provider, the body follows the format of the endpoint you called. Chat Completions and Responses get `{"error": {"message", "type", "code", "param"}}`. Messages gets `{"type": "error", "error": {"type", "message"}}`. The message may end with `Reference code: …`. Include that code if you contact support.

## Status codes

| Status | Meaning | What to do |
|---|---|---|
| **400** | The request is invalid: malformed JSON, a missing or overlong `model` (max 128 characters), an out-of-range `max_tokens`, conflicting output-limit fields, an unsupported effort value, a model not available on this format, or a prompt longer than the model's context window (`context_length_exceeded`). | Fix the request. Don't retry it unchanged. |
| **401** | The API key is missing or invalid. | Check the header and key. See [Authentication](https://7api.st/docs/authentication). |
| **402** | `insufficient_balance`. Either the balance is zero, or this request's worst-case cost (input plus the full `max_tokens`) is more than the remaining balance. | Top up, or lower `max_tokens`. |
| **403** | `permission_denied`: the key can't use this model. An upstream safety block can also return 403 `permission_error`. | Use another model, or rephrase. |
| **404** | Unknown endpoint, or a model that is retired or temporarily unavailable (`model_unavailable`). | Check the path and the [model list](https://7api.st/pricing). |
| **405 / 415** | Wrong HTTP method, or the body isn't JSON (`Content-Type` must be `application/json`). | Use POST with a JSON body. |
| **413** | The request body is larger than 25 MB. | Send fewer or smaller images, or trim the history. |
| **429** | A [rate limit](https://7api.st/docs/rate-limits) was hit (`rate_limit_error`), or the upstream is busy. | Wait for the `Retry-After` header, then retry with backoff. |
| **500** | Internal error | Retry with backoff. |
| **502 / 503** | No upstream could serve the request right now (`overloaded_error` on Anthropic format), or the gateway is briefly busy. | Retry with backoff. Check [status](https://7api.st/status) if it persists. |

## Retry policy

Retry `429`, `500`, `502`, `503` and `504` with exponential backoff and jitter, honoring `Retry-After` when it's present. Don't retry other `4xx` errors unchanged.

The gateway already fails over between upstream providers before it returns an error. A 5xx means that failover was also exhausted, so waiting a little before retrying helps more than retrying immediately.

## Billing on errors

A request that fails without delivering any output isn't charged. If a stream fails partway, you pay only for the tokens that were delivered.
