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

# Errors & status codes

> The HTTP status codes and error bodies FortAPI returns, and what to do about each

When a request fails, FortAPI tells you why with an HTTP status code plus a JSON error body. The body's shape depends on the protocol you're using.

## Error body format

**OpenAI protocol** (`/v1/chat/completions`, etc.):

```json theme={null}
{
  "error": {
    "message": "insufficient user quota (request id: 2025...-abc)",
    "type": "insufficient_quota",
    "param": "",
    "code": "insufficient_user_quota"
  }
}
```

**Claude protocol** (`/v1/messages`):

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "upstream temporarily overloaded, retry shortly"
  }
}
```

<Note>
  The `message` usually ends with a `request id`. Include it when contacting support — it's the fastest way to locate that request's logs.
</Note>

## Status codes

| Status | Meaning                                                                                               | What to do                                                                                                                                       |
| ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`  | Auth failed: key missing, mistyped, disabled, or deleted                                              | Confirm you're using a FortAPI token (`sk-...`) with no stray whitespace/newlines; check it's still enabled under **Tokens** in the console      |
| `403`  | Insufficient balance, token/account banned, or group has no access to that model                      | Top up, or switch to a model you have access to; check the token's model allowlist doesn't exclude it (**insufficient balance is 403, not 402**) |
| `404`  | Model doesn't exist, or wrong request path                                                            | Verify the model name (per the Pricing page); OpenAI `base_url` includes `/v1`, Anthropic SDK's `ANTHROPIC_BASE_URL` does not                    |
| `429`  | Rate limited (too many requests)                                                                      | Back off and retry — see [Rate limits](/en/rate-limits)                                                                                          |
| `500`  | Internal server error                                                                                 | Usually transient; retry shortly. If persistent, contact support with the request id                                                             |
| `503`  | No upstream channel available, or system overloaded                                                   | Retry shortly or switch models; if persistent, contact support                                                                                   |
| `529`  | Upstream provider (e.g. Anthropic) overloaded — passed through verbatim, `type` is `overloaded_error` | A transient upstream state; exponential-backoff retry usually recovers                                                                           |

## Telling which layer an error came from

* Errors **from FortAPI itself** usually have `type` of `new_api_error` or a standard type (`insufficient_quota`, `invalid_request_error`, …).
* Errors **from the upstream provider** (e.g. `rate_limit_error`, `overloaded_error`) are **passed through verbatim**, preserving the upstream status code and type, with per-channel retry where applicable. Seeing `overloaded_error` / `rate_limit_error` generally points to an upstream-side issue.

## Retry guidance

For **transient** errors (`429` / `500` / `503` / `529`), retry with **exponential backoff** (e.g. 1s, 2s, 4s… with a little jitter) rather than hammering — tight retries make rate limiting worse. `401` / `403` / `404` are **configuration** errors; retrying won't help — fix the config per the table above.