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

# Inference errors

> Error codes returned by Hyperbolic Inference, what each one means, and how to fix it.

When Hyperbolic can't accept an inference request, it returns an HTTP error status. Use the status code to decide whether to retry.

* **Authentication, plan, and balance errors** (`401`, `402`, `403`) return a JSON body with `code` and `message` at the top level, as shown below. The status says which kind of problem it is; use the `code` to decide what to fix.
* **Other errors** can come from the API gateway, the model server, or an upstream model provider, and their body format varies. Handle them by HTTP status code. For example, an unknown model ID returns `404` with `{"message": "Model not found", "type": "Not Found", "code": 404}`.

The OpenAI SDKs raise an exception with the status code for every error.

## Authentication, plan, and balance errors

Requests that fail an authentication, plan, or balance check return one of three statuses, each with a `code` and a readable `message`:

* `401`: the credential is missing, invalid, or expired.
* `402`: the account or Organization has no credits left.
* `403`: the account's plan doesn't include inference.

```json theme={null}
{
  "code": "api_key_invalid",
  "message": "..."
}
```

The `message` says what to do next and may change. The `code` doesn't change, so branch on `code` in your client.

| Status | `code` | Meaning | What to do |
| - | - | - | - |
| `401` | `api_key_missing` | No API key was sent | Send your key in the `Authorization` header as `Bearer YOUR_API_KEY` |
| `401` | `api_key_malformed` | The credential isn't an API key the service accepts | Use an `sk_live_` key from **Settings > API Keys** |
| `401` | `api_key_invalid` | The key doesn't exist or is wrong | Check the key, or create a new one |
| `401` | `api_key_revoked` | The key was revoked | Create a new key under **Settings > API Keys** |
| `401` | `legacy_key_unsupported` | The key uses the older format from the previous inference API | Create a new `sk_live_` key |
| `401` | `account_not_found` | No account matches the dashboard session | Sign in again. Contact support if it persists |
| `401` | `account_plan_unknown` | Hyperbolic couldn't read your plan | Contact [support](mailto:support@hyperbolic.ai) |
| `401` | `session_expired` | The dashboard session expired | Sign in again |
| `401` | `session_invalid` | The dashboard session couldn't be verified | Sign in again |
| `402` | `insufficient_balance` | The account or Organization has no credits left | Add credits under **Billing** |
| `403` | `inference_requires_pro` | The personal account is on the Free Tier | Upgrade with a one-time \$5 deposit under **Settings > Plan**, or use an Organization API key |

The `session_*` and `account_not_found` codes apply to requests from the Model Playground, which uses your dashboard session instead of an API key.

> [!TIP]
>
> After you upgrade your plan, retry after about 30 seconds. After you add credits, retry after a minute or two.

## Other status codes

| Status | Meaning | What to do |
| - | - | - |
| `400` | The request isn't valid. For `glm-5.3-flash`, this includes a prompt plus `max_tokens` that doesn't fit in the context window | Check the request body, or shorten the prompt or lower `max_tokens`. Don't retry it unchanged |
| `404` | The model ID doesn't exist, or the URL is wrong. Requests to the previous API at `api.hyperbolic.xyz` return `404` | Use a model ID from [Available models](https://hyperbolic.ai/docs/inference/overview.md#available-models) and the base URL `https://api.hyperbolic.ai/inference/v1` |
| `429` | The API key sent more than 300 requests in a minute | Retry with exponential backoff. For a higher limit, [contact sales](mailto:sales@hyperbolic.ai) |
| `500`, `502`, `503`, `504` | Hyperbolic or the model is temporarily unavailable. A `503` can also mean the authentication check timed out | Retry with exponential backoff. Contact support if it persists |

You aren't charged for requests that return an error.

## Retry with backoff

Retry `429` and `5xx` responses, waiting longer after each attempt. Don't retry `400`, `401`, `402`, or `403` responses, because the same request fails again until you fix it: the request, the credential, the balance, or the plan.

```python theme={null}
import time
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def chat(data, api_key, max_retries=4):
    url = "https://api.hyperbolic.ai/inference/v1/chat/completions"
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_retries + 1):
        response = requests.post(url, headers=headers, json=data, timeout=120)
        if response.status_code not in RETRYABLE or attempt == max_retries:
            response.raise_for_status()
            return response.json()
        time.sleep(2 ** attempt)  # 1, 2, 4, 8 seconds
```

The OpenAI SDKs retry `429` and `5xx` responses automatically. Set `max_retries` (Python) or `maxRetries` (Node.js) on the client to change how many times.

## Next steps

> **[Account management](https://hyperbolic.ai/docs/general/account-management.md#api-keys)**
>
> Create and revoke API keys.

> **[Getting support](https://hyperbolic.ai/docs/general/support.md)**
>
> Contact the team about persistent errors.


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