Ошибки
Все коды ошибок API и что с ними делать.
Ошибка приходит с HTTP-статусом и телом в формате эндпоинта. Для /v1/chat/completions, /v1/responses, /v1/embeddings, картинок, видео и речи:
{
"error": {
"type": "insufficient_quota_error",
"code": "insufficient_funds",
"message": "organization balance insufficient for this request"
}
}В формате OpenAI ориентируйтесь на error.code: он стабилен, а текст сообщения может измениться.
Для /v1/messages тело в формате Anthropic: {"type": "error", "error": {"type": "...", "message": "..."}}. Поля error.code в нём нет, кроме key_revoked. Ошибку определяют по HTTP-статусу, error.type и тексту error.message:
| Статус | error.type | Коды из таблиц ниже |
|---|---|---|
| 400, 404, 413 | invalid_request_error | запрос, model_not_found, request_too_large |
| 401 | authentication_error | invalid_api_key, key_revoked |
| 402 | insufficient_quota_error | insufficient_funds, key_limit_exceeded, spend_limit_exceeded |
| 403 | permission_error | model_not_allowed, pii_masking_not_enabled, account_blocked |
| 429 | rate_limit_error | rate_limit_exceeded |
| 500, 502, 503 | api_error | internal_error, provider_error, service_unavailable |
Ошибки до резерва денег (401, 403, 404, 400 и 413) ничего не стоят.
В каждом ответе есть заголовок X-Request-Id. Назовите его в поддержке, если нужно разобрать запрос.
Запрос
invalid_jsonТело запроса не разобрано. Проверьте JSON.model_category_mismatchКатегория модели не подходит к эндпоинту: модель эмбеддингов или видео в /v1/chat/completions, модель картинок в /v1/messages, /v1/responses или /v1/embeddings, текстовая модель в /v1/images/generations или /v1/embeddings. Модель картинок в /v1/chat/completions разрешена. Выберите модель нужной категории из списка.stateful_not_supportedВ /v1/responses переданы store: true или previous_response_id. Уберите поля и отправляйте всю историю в каждом запросе.invalid_pii_masking_headerВ X-PII-Masking значение не из списка on, off, true, false, 1, 0.pii_masking_unsupported_endpointX-PII-Masking: on на эндпоинте без маскирования: эмбеддинги, речь, картинки. Уберите заголовок или поставьте off.unsupported_response_formatДля картинок запрошен response_format: "url". Используйте b64_json.image_streaming_unsupportedДля картинок передан stream: true. Уберите поле.invalid_image_countn в запросе картинок не целое число от 1 до 10.unsupported_video_parameterДлительность, разрешение или соотношение сторон не входят в список модели видео, либо передан файл в input_reference. Допустимые значения смотрите у модели.invalid_secondsДлительность видео не разобрана. Передайте число секунд.missing_promptВ запросе видео нет prompt.missing_modelВ запросе видео нет model.invalid_multipartMultipart-тело запроса речи не разобрано.request_too_largeТело больше 32 МиБ (26 МиБ для речи). Уменьшите запрос.Ключ и доступ
invalid_api_keyКлюч не передан, неверный, отозван или истёк. Проверьте заголовок и состояние ключа в кабинете.key_revokedКлюч отозвали, пока запрос шёл. Запрос оборван, в потоке ошибка приходит последним событием. Расход считается по уже полученному.model_not_allowedМодели нет в списке ключа. Выберите модель из GET /v1/models или расширьте список в кабинете.pii_masking_not_enabledПередан X-PII-Masking: on, а опция маскирования не подключена организации. Уберите заголовок или подключите опцию.account_blockedОрганизация заблокирована или не активна. Обратитесь в поддержку.model_not_foundТакой модели нет в каталоге. Сверьте имя с GET /v1/models.Деньги и лимиты
insufficient_fundsНа балансе не хватает денег на резерв запроса. Пополните баланс или передайте меньший max_tokens.key_limit_exceededИсчерпан дневной или месячный денежный лимит ключа. В сообщении указан период, для лимита по типу или модели ещё kind или model. Подождите начала периода или поднимите лимит.spend_limit_exceededИсчерпан лимит расхода сотрудника, команды или организации. В сообщении указаны область и период.rate_limit_exceededБольше 120 запросов или 200 000 токенов в минуту. Повторите через время из заголовка Retry-After.В формате Anthropic три причины 402 различаются текстом error.message:
organization balance insufficient for this request:insufficient_funds;spending limit of this API key for the <период> is exceeded:key_limit_exceeded(для лимита по типу или модели в конце добавленоfor <тип> generationилиfor model <модель>);spending limit of the <область> for the <период> is exceeded:spend_limit_exceeded.
Видео
video_not_foundЗадачи нет или она принадлежит другой организации.video_not_readyФайл запрошен до завершения задачи. Проверьте статус через GET /v1/videos/{id}.video_cancel_unsupportedОтменить задачу, уже переданную провайдеру, нельзя. Дождитесь завершения.Если генерация видео закончилась статусом failed, деньги не списываются. Причина лежит в поле error задачи: например timeout (задача не закончилась за час), provider_error, cancelled, key_revoked.
Сервис и провайдер
provider_errorПровайдер модели отклонил запрос. Повторите позже.internal_errorВнутренняя ошибка. Повторите запрос и сообщите X-Request-Id, если она не проходит.Ошибку самого провайдера (недоступность модели, модерация, региональные ограничения) сервис отдаёт как есть, в формате провайдера, с его статусом и телом. Любой такой статус с Retry-After можно повторять после паузы.
Безопасно повторять 429, 502 и 503: при 503 деньги не резервировались. Перед повтором 402 пополните баланс или лимит, перед повтором 400 и 403 исправьте запрос.