# Errors

Source: https://docs.aicentos.com/en/billing/errors

Language: en

> HTTP status codes, error response structure, common errors and solutions

aicentos follows the **OpenAI error response format** exactly. When an SDK throws, just catch the corresponding exception.

## Error response structure

Every error response has this shape:

```bash
{
  "error": {
    "message": "Your API key does not have access to gpt-5",
    "type": "permission_denied",
    "code": "model_not_allowed",
    "param": "model"
  }
}
```

| Field     | Meaning                                           |
| --------- | ------------------------------------------------- |
| `message` | Human-readable error description                  |
| `type`    | Error category (see table below)                  |
| `code`    | Fine-grained error code (for programmatic checks) |
| `param`   | Name of the offending parameter, if any           |

## HTTP status code reference

| Status | Type                     | Common causes                                                     |
| ------ | ------------------------ | ----------------------------------------------------------------- |
| `400`  | `invalid_request_error`  | Malformed request body, invalid parameters, misspelled model name |
| `401`  | `authentication_error`   | API key missing / wrong / revoked                                 |
| `402`  | `insufficient_quota`     | Insufficient balance                                              |
| `403`  | `permission_denied`      | Key disabled, model not authorized, IP not on the allowlist       |
| `404`  | `not_found`              | Wrong endpoint path, wrong model ID                               |
| `408`  | `request_timeout`        | Upstream timeout (usually no response for over 60s)               |
| `413`  | `payload_too_large`      | Request body too large (images, files)                            |
| `415`  | `unsupported_media_type` | Wrong Content-Type                                                |
| `422`  | `invalid_request_error`  | Request body parses but is semantically invalid                   |
| `429`  | `rate_limit_exceeded`    | Rate limit hit; lower the request rate and retry                  |
| `500`  | `server_error`           | Internal platform error (rare)                                    |
| `502`  | `bad_gateway`            | Upstream service failure                                          |
| `503`  | `service_unavailable`    | Upstream overloaded; retry later                                  |
| `504`  | `gateway_timeout`        | Upstream response timed out                                       |

## Common errors and fixes

### 401 — Invalid API key

```bash
{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }
```

**Checklist**:

* Is the `Authorization` header in `Bearer sk-xxx` format (note the space)
* Did copying the key from the console pick up spaces / newlines
* Is the key deleted / disabled / expired
* Did a test key end up in production

### 402 — Insufficient quota

```bash
{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }
```

Top up → **Wallet Management** in the console. Turn on [balance alerts](https://docs.aicentos.com/en/billing/pricing#balance-alerts) to keep it from happening again.

### 403 — Model not allowed

```bash
{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }
```

The token was created with an **allowed models** allowlist, and the requested model is not on it. Change the token settings or use another key.

### 404 — Model not found

```bash
{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }
```

The model ID is misspelled or has been retired. Check the [model marketplace](https://aicentos.com/pricing) for currently available IDs.

### 429 — Rate limit exceeded

The `Retry-After` response header tells you how many seconds to wait before retrying. Lower your concurrency and request rate to recover.

### 500 / 502 / 503 — Service errors

Usually upstream turbulence. **Retrying 2-3 times automatically** usually succeeds. If it lasts more than 5 minutes:

* Check the [status page](https://status.aicentos.com) (if available)
* Contact support

### 408 / 504 — Timeouts

No response after 60 seconds. Common causes:

* The prompt is so long that the model "thinks" past the timeout
* Streaming is not enabled (add `stream: true` for long responses)

**Fixes**:

* Shorten the prompt
* Enable streaming: `{ "model": "...", "messages": [...], "stream": true }`
* Switch to a faster model (e.g. from `gpt-4o` to `gpt-4o-mini`)

## SDK error handling examples

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"
```

### Python

```python
import os
from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1")

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry in {e.response.headers.get('Retry-After')}s")
except APIError as e:
    print(f"Other API error: {e.status_code} {e.message}")
```

### Node.js

```js
import OpenAI, { APIError } from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

try {
  const resp = await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.code, err.message);
  }
}
```

## Retry and fallback recommendations

| Error type                            | Recommended handling                                |
| ------------------------------------- | --------------------------------------------------- |
| `400` / `401` / `402` / `403` / `404` | **Do not retry** — code / config error; debug first |
| `429`                                 | Retry per `Retry-After` with exponential backoff    |
| `500` / `502` / `503` / `504` / `408` | Retry 1-3 times immediately, 1-5s apart             |

The official OpenAI SDKs ship with sensible retry policies by default — **use the SDK in production code instead of hand-rolled fetch calls**.