Коды ошибок

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

При ошибке эндпоинт /v1 возвращает статус 4xx / 5xx и JSON, как в примере ниже: message — текст для человека, type — общий класс ошибки, code — стабильный машиночитаемый идентификатор, а param называет поле, в котором ошибка (null, если такого поля нет). Ориентируйтесь на HTTP-статус и code, а не на текст message: он может быть на английском, на китайском или на обоих языках сразу, и его формулировки меняются.

{
  "error": {
    "message": "Insufficient balance — please top up",
    "type": "insufficient_quota",
    "code": "insufficient_quota",
    "param": null
  }
}

Эндпоинты /anthropic используют собственный формат Anthropic, без code и param; ориентируйтесь на HTTP-статус и error.type:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: gpt-5.5"
  }
}

• Некоторые ошибки содержат дополнительные поля верхнего уровня, например attempts, когда заняты все линии, или retry_after, когда свободной линии временно нет. Незнакомые поля просто игнорируйте.
• Если поставщик модели отклоняет запрос (например, из-за слишком длинного контекста), в message — формулировка самого поставщика, а в code — его значение или invalid_request, если он его не передал.

HTTP-статусы: краткая сводка

Все коды ошибок

Ошибки, которые возвращает шлюз, по категориям. Одному HTTP-статусу может соответствовать несколько кодов, поэтому ориентируйтесь на code.

Авторизация и аккаунт

Лимиты, заданные для ключа

Сам запрос

Статус модели

Загрузка и резерв

Ошибки поставщика (эндпоинты чата)

Если эндпоинт чата (/v1/chat/completions, /v1/responses, /anthropic/v1/messages) получает ошибку, шлюз сначала повторяет запрос на других линиях и возвращает одну из этих ошибок, только когда ошибкой завершились все линии. Ни одна из них не оплачивается.

Эндпоинты Anthropic

• error.type принимает стандартные значения Anthropic в зависимости от статуса: 400 invalid_request_error, 401 authentication_error, 402 billing_error, 403 permission_error, 404 not_found_error, 429 rate_limit_error (overloaded_error, когда заняты все линии), 502 api_error, 503 overloaded_error (api_error, пока модель на обслуживании).
• /anthropic принимает только модели Claude; на любую другую модель вернётся 404 not_found_error.
• max_tokens обязателен и не может быть равен 0, иначе вернётся 400.

Неудачные задачи (изображения и видео)

Если задача изображения или видео завершилась ошибкой уже после того, как была принята, эндпоинт задачи всё равно отвечает HTTP 200, а status равен failed; причина — в error, а error.code принимает одно из значений ниже. Зарезервированные под задачу кредиты уже вернулись на баланс. С вебхуком вы получите image.failed / video.failed с тем же содержимым.

Полное руководство по асинхронным задачам →

Ошибки посреди потока

• Когда потоковый запрос уже ответил HTTP 200 и начал передачу, последующая ошибка не может изменить статус: она либо приходит как событие данных с error, либо поток просто заканчивается.
• Проверяйте, что поток пришёл целиком: в формате OpenAI должны прийти finish_reason и data: [DONE], в формате Anthropic — message_stop. Если их нет, считайте поток оборванным.
• Оборвавшийся поток оплачивается по объёму, сгенерированному до обрыва; подробнее — в разделе Оплата и возвраты.

Оплачиваются ли ошибки?

• Запрос, вернувший ошибку, никогда не оплачивается: либо ошибка возникает до списания, либо резерв возвращается полностью.
• За неудачные задачи изображений и видео деньги возвращаются полностью.
• Единственное исключение — поток, который уже начался: если он оборвётся, вы платите за то, что успело сгенерироваться до обрыва.

Когда повторять запрос

При 4xx сначала исправьте запрос (при 402 пополните баланс, при 429 немного подождите); ошибки 5xx и таймауты можно повторять без изменений, с экспоненциальной задержкой, а если есть Retry-After — ждать столько, сколько в нём указано.

Стратегия повторов и пример кода →