# Errors

> Every status code the gateway returns, what actually causes it, and the fix.

_Source: https://aiprimetech.io/docs/api-reference/errors/ · Home > Docs > API reference_

Errors return JSON with a `type` and a human-readable `message`. Status codes follow the Anthropic and OpenAI conventions.

```json
{"type": "error", "error": {"type": "authentication_error", "message": "invalid api key"}}
```


## Status codes

| Code | Meaning | Most common real cause | Fix |
|---|---|---|---|
| `400` | Bad request | Missing `max_tokens` on Messages, or a malformed `messages` array | Check the body against [Messages](/docs/api-reference/messages/) |
| `401` | Unauthenticated | Key sent in the wrong header for the format | `x-api-key` for Messages, Bearer for Chat Completions |
| `402` | Payment required | Balance exhausted or plan expired | [Top up](/topup/) or [buy a plan](/plans/) |
| `403` | Forbidden | Key revoked, or model not enabled for the account | Create a new key; check `/v1/models` |
| `404` | Not found | Base-URL mistake — usually a doubled or missing `/v1` | See [Base URLs](/docs/getting-started/base-urls/) |
| `429` | Rate limited | Too many concurrent requests | Back off exponentially; see [Rate limits](/docs/api-reference/rate-limits/) |
| `500` | Gateway error | Unexpected internal failure | Retry once; if it persists, contact support with the request id |
| `529` | Upstream overloaded | Provider capacity, not your account | Retry with backoff — usually clears in seconds |


## Error types

| type | Meaning |
|---|---|
| `invalid_request_error` | The body is malformed or a required field is missing |
| `authentication_error` | Key missing, malformed, or revoked |
| `permission_error` | Key is valid but not allowed to use that model |
| `not_found_error` | Unknown path or unknown model id |
| `rate_limit_error` | Throttled |
| `api_error` | Internal failure |
| `overloaded_error` | Upstream capacity exhausted |


## Retrying correctly

Retry `429`, `500`, `502`, `503` and `529`. Never blind-retry `400`, `401`, `402` or `403` — the same request fails identically, and for partially generated responses you may pay twice.

```python
import time, httpx

def call(body, key, tries=4):
    for i in range(tries):
        r = httpx.post("https://aiprimetech.io/v1/messages", json=body, timeout=120,
                       headers={"x-api-key": key,
                                "anthropic-version": "2023-06-01"})
        if r.status_code in (429, 500, 502, 503, 529):
            time.sleep(2 ** i)          # 1s, 2s, 4s, 8s
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError("upstream unavailable after retries")
```

> Add jitter to the sleep in production. Synchronised retries from many workers turn one blip into a thundering herd against the same upstream.

- [Rate limits](https://aiprimetech.io/docs/api-reference/rate-limits/) — Concurrency and throughput
- [Troubleshooting](https://aiprimetech.io/docs/guides/troubleshooting/) — Symptom-first index


---
_ClaudeAPIKey.dev is an independently operated, Anthropic-compatible API gateway. Not affiliated with Anthropic._