Распространённые ошибки

Формат ошибки

{
    "error": {
        "type": "invalid_request_error",
        "code": "model_not_found",
        "message": "The model 'gpt-9' does not exist or you do not have access to it.",
        "param": "model",
        "request_id": "req_01HFQX..."
    }
}

401 — Unauthorized

Причины:

• Не передан заголовок Authorization.
• Ключ опечатан, отозван или удалён.
• Ключ создан в другом аккаунте.

Как починить: создайте новый ключ в личном кабинете, проверьте, что в коде используется именно он, и нет лишних пробелов.

402 — Payment Required

Баланс закончился. Пополните счёт в личном кабинете — сервис автоматически возобновит работу.

403 — Forbidden

Ключу запрещён доступ к выбранному провайдеру или модели — например, у ключа выставлен whitelist. Откорректируйте права ключа в разделе «API-ключи».

404 — Not Found

Неверный путь или несуществующая модель. Сверьтесь с документацией провайдера и таблицей моделей в разделе «Модели и цены».

408 — Request Timeout

Запрос не уложился в тайм-аут (по умолчанию 10 минут). Уменьшите max_tokens, разбейте задачу на части или включите стриминг.

413 — Payload Too Large

Тело запроса больше 20 МБ. Сожмите изображение, разбейте контекст или используйте file_id через Files API.

422 — Unprocessable Entity

Запрос синтаксически верный, но не соответствует схеме провайдера: неверные поля, конфликтующие параметры. Смотрите error.message и error.param.

429 — Too Many Requests

Превышен лимит. Подождите время, указанное в заголовке Retry-After, и повторите запрос. Подробнее в «Лимитах».

500 / 502 / 503 — ошибки на стороне провайдера

Временные сбои у провайдера или промежуточных узлов. Достаточно повторить запрос с экспоненциальной задержкой. Если ошибка устойчивая — проверьте статус сервиса в личном кабинете или напишите в поддержку.

504 — Gateway Timeout

Провайдер не ответил за разумное время. Чаще всего возникает у моделей с большим reasoning. Включите стриминг или увеличьте тайм-аут на стороне клиента.

Отладка

1. Сохраните X-Request-Id из ответа в логах своего сервиса.
2. Откройте журнал в личном кабинете — найдите запрос по этому идентификатору.
3. Сравните отправленный body и ответ провайдера. В 90% случаев проблема видна сразу.