# Ошибки

Источник: https://docs.aicentos.com/ru/billing/errors

Language: ru

> HTTP-коды состояния, структура ответа с ошибкой, частые ошибки и способы их устранения

aicentos полностью придерживается **формата ошибок OpenAI**. Если ошибку бросает SDK, достаточно перехватить соответствующее исключение.

## Структура ответа с ошибкой

Все ответы с ошибкой имеют такой вид:

```bash
{
  "error": {
    "message": "У вашего API-ключа нет доступа к gpt-5",
    "type": "permission_denied",
    "code": "model_not_allowed",
    "param": "model"
  }
}
```

| Поле      | Значение                                         |
| --------- | ------------------------------------------------ |
| `message` | понятное человеку описание ошибки                |
| `type`    | категория ошибки (см. таблицу ниже)              |
| `code`    | детальный код ошибки (для программной обработки) |
| `param`   | имя поля, вызвавшего ошибку (если есть)          |

## Шпаргалка по HTTP-кодам

| Код   | Тип                      | Типичные причины                                                            |
| ----- | ------------------------ | --------------------------------------------------------------------------- |
| `400` | `invalid_request_error`  | неверный формат тела запроса, недопустимый параметр, опечатка в имени model |
| `401` | `authentication_error`   | API-ключ отсутствует / неверный / отозван                                   |
| `402` | `insufficient_quota`     | недостаточно средств                                                        |
| `403` | `permission_denied`      | ключ отключён, модель не разрешена, IP не в белом списке                    |
| `404` | `not_found`              | неверный путь эндпоинта, неверный ID модели                                 |
| `408` | `request_timeout`        | таймаут апстрима (обычно нет ответа дольше 60 с)                            |
| `413` | `payload_too_large`      | слишком большое тело запроса (изображения, файлы)                           |
| `415` | `unsupported_media_type` | неверный Content-Type                                                       |
| `422` | `invalid_request_error`  | тело запроса разбирается, но семантика неверна                              |
| `429` | `rate_limit_exceeded`    | сработало ограничение частоты; снизьте частоту и повторите                  |
| `500` | `server_error`           | внутренняя ошибка платформы (редко)                                         |
| `502` | `bad_gateway`            | сбой апстрим-сервиса                                                        |
| `503` | `service_unavailable`    | перегрузка апстрима, попробуйте позже                                       |
| `504` | `gateway_timeout`        | таймаут ответа апстрима                                                     |

## Частые ошибки и решения

### 401 — Invalid API key

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

**Чек-лист проверки**:

* Заголовок `Authorization` в формате `Bearer sk-xxx` (важен пробел)
* Не попали ли в ключ пробелы / переводы строк при копировании из консоли
* Не удалён ли ключ / не отключён ли / не истёк ли срок его действия
* Не оказался ли тестовый ключ в продакшене

### 402 — Insufficient quota

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

Пополните баланс: консоль → «Кошелёк». Включите [предупреждение о балансе](https://docs.aicentos.com/ru/billing/pricing#%D0%BF%D1%80%D0%B5%D0%B4%D1%83%D0%BF%D1%80%D0%B5%D0%B6%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5-%D0%BE-%D0%B1%D0%B0%D0%BB%D0%B0%D0%BD%D1%81%D0%B5), чтобы ситуация не повторилась.

### 403 — Model not allowed

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

При создании токена был отмечен белый список «**доступные модели**», и запрошенная model в него не входит. Измените настройки токена или возьмите другой ключ.

### 404 — Model not found

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

ID модели указан с опечаткой либо модель снята с обслуживания. Актуальные доступные ID смотрите в [витрине моделей](https://aicentos.com/pricing).

### 429 — Rate limit exceeded

Заголовок ответа `Retry-After` подсказывает, через сколько секунд повторить запрос. Достаточно снизить параллелизм и частоту запросов — и всё восстановится.

### 500 / 502 / 503 — сбой сервиса

Обычно это колебания апстрима. **2–3 автоматических повтора** чаще всего решают проблему. Если длится дольше 5 минут:

* проверьте [страницу статуса](https://status.aicentos.com) (если доступна)
* обратитесь в поддержку

### 408 / 504 — таймауты

Запрос висит без ответа дольше 60 с. Частые причины:

* слишком длинный prompt — модель «думает» дольше таймаута
* не включён стриминг (для длинных ответов добавьте `stream: true`)

**Решение**:

* сократите prompt
* включите стриминг: `{ "model": "...", "messages": [...], "stream": true }`
* переключитесь на более быструю модель (например, с `gpt-4o` на `gpt-4o-mini`)

## Примеры обработки ошибок в SDK

```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("Неверный ключ")
except RateLimitError as e:
    print(f"Лимит запросов, повтор через {e.response.headers.get('Retry-After')} с")
except APIError as e:
    print(f"Другая ошибка API: {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);
  }
}
```

## Рекомендации по повторам и деградации

| Тип ошибки                            | Рекомендация                                                           |
| ------------------------------------- | ---------------------------------------------------------------------- |
| `400` / `401` / `402` / `403` / `404` | **не повторять** — ошибка в коде или конфигурации, сначала разберитесь |
| `429`                                 | повторять по `Retry-After`, с экспоненциальной задержкой               |
| `500` / `502` / `503` / `504` / `408` | сразу 1–3 повтора с интервалом 1–5 с                                   |

В официальных SDK OpenAI по умолчанию заложена разумная политика повторов — **в продакшене используйте SDK, а не собственный fetch**.