Ошибки
Конверт, в котором приходит отказ, коды ответа шлюза и два поведения, которые должен учитывать клиент.
Быстро
Вот вся таблица решений. Подробности каждой строки — в разделах ниже.
| Код | Причина | Что делать |
|---|---|---|
400 | Запрос невалиден: искажённое тело, член, которого эта поверхность не принимает, или запрос сверх лимита (request_limit_exceeded). | Починить тело; для request_limit_exceeded — уменьшить то, что называет limit.name. Повторять нечего — тот же запрос отвергнется так же. |
401 | Запрос не аутентифицирован. | Проверить заголовок и сам ключ. Не повторять. |
402 | Платить нечем: кошелёк пуст или исчерпан пакет, из которого тратит ключ. | Пополнить кошелёк или купить пакет, либо переключить ключ на баланс. Не повторять. |
403 | Ключу не разрешено вызывать эту модель, либо организация заморожена. | Проверить область ключа и состояние организации в консоли. Не повторять. |
404 | Такой модели нет. | Сверить имя с опубликованным каталогом. Не повторять. |
422 | Запрос валиден, но модель не может сделать то, о чём он просит, — например, принять принудительный вызов инструмента (tool_choice_unsupported). | Изменить запрос: для tool_choice_unsupported — отправить tool_choice: "auto" или не задавать его. Без изменений не повторять. |
429 | Вызов вышел за потолок темпа или трат. | Отступить и повторить позже, удлиняя паузу с каждой попыткой и ограничив их число. |
500 | Запрос не удалось выполнить. | Отступить и повторить не сразу. Вслепую в цикле — нет: исход наверху мог остаться неизвестным. |
503 | Ни один провайдер сейчас не может обслужить этот запрос. | Отступить и повторить позже. Немедленный повтор не помогает: наверху ничего не изменилось. |
Ни один отказ не лечится немедленным повтором. Клиент, который считает любую ошибку поводом «попробовать сейчас же», тратит на отказы всю свою квоту.
Конверт отказа
Отклонённый вызов отвечает одним JSON-объектом с единственным членом error. Это собственный конверт протокола, а не перевод чужого: одна и та же форма отказывает вызову Chat Completions, вызову Responses и вызову Messages, а поверхность Messages оборачивает её верхнеуровневым "type": "error", которого ждут её клиенты.
Два члена есть всегда — type и message; ещё три появляются, когда есть что сказать.
typeКласс отказа в собственном закрытом словаре протокола: invalid_request_error, not_found_error, authentication_error, permission_error, rate_limit_error, api_error, а на поверхности Messages ещё overloaded_error и billing_error — `402` на Messages имеет тип billing_error.messageЧто пошло не так — фиксированной безопасной фразой. Она никогда не цитирует содержимое запроса, поэтому не может вывести в лог ни промпт, ни заголовок, ни ключ. Единственное, что она может назвать, — модель, и только после того, как опубликованный каталог принял это имя: это имя из каталога, а не произвольный текст.codeМашиночитаемая причина. У одной причины одно написание на всех поверхностях платформы — потому именно на неё и ветвится клиент.paramЧлен запроса, в котором дело, — когда дело в одном члене.limitПри отказе `request_limit_exceeded` — какой лимит, сам лимит и значение, до которого дошёл запрос; см. [запрос сверх лимита](#request-limit-exceeded).Ветвитесь на type и на code, но никогда — на формулировке message: она выбрана так, чтобы её было безопасно печатать, а не так, чтобы её разбирали.
{
"error": {
"type": "authentication_error",
"message": "The request is not authenticated."
}
}Коды ответа
400Запрос невалиден: искажённое тело, член, которого эта поверхность не принимает, или запрос сверх лимита (`request_limit_exceeded`).401Запрос не аутентифицирован.402Платить нечем: кошелёк пуст (`insufficient_wallet_balance`) или пакет ключа исчерпан (`insufficient_package_balance`). Отказ решается до обращения к провайдеру.403Ключу не разрешено вызывать эту модель, либо организация заморожена.404Такой модели нет.422Запрос валиден, но модель или её маршруты не могут сделать то, о чём он просит, — например, принять принудительный вызов инструмента (`tool_choice_unsupported`). Тот же запрос отвергается так же, пока он не изменится.429Запрос отклонён лимитом темпа или лимитом трат.500Запрос не удалось выполнить.503Ни один провайдер сейчас не может обслужить этот запрос.Два из них стоит различать до того, как написан повтор. 429 — это потолок, выше которого вы оказались, и лечит его время; 503 означает, что сейчас вызов не может обслужить никто наверху. Ни один из них не лечится немедленным повтором, а клиент, считающий любой отказ поводом «повторить сейчас же», тратит на отказы всю свою квоту.
Запрос сверх лимита
Запрос, превысивший один из лимитов запроса шлюза, отклоняется с кодом ответа 400, кодом request_limit_exceeded и типом invalid_request_error — до того, как что-либо отправлено провайдеру. Это слишком много инструментов или сообщений, слишком длинный текст, имя, описание или схема инструмента, текст или картинки запроса сверх его бюджета, слишком много или слишком большие картинки, слишком длинный адрес картинки, картинка в формате, который шлюз не передаёт, и целое число сверх опубликованного максимума — например, max_tokens выше потолка вывода. Отказ говорит, какой лимит, где и насколько он превышен:
param— путь к члену, в котором дело, напримерtoolsилиmessages[3].content[1].text. Лимит на запрос целиком член не называет.messageназывает лимит, значение, до которого дошёл запрос, сам лимит и что делать.limitнесёт то же для программы:name— какой это лимит (tools,text_length,tool_schema_size,request_text_size,images,image_size,image_url_size,image_format,output_tokensи остальные), аmaxиactual— в единицахunit:items,code_points,bytes,tokensилиnumber. Уimage_formatчисел нет:acceptedперечисляет форматы, которые шлюз передаёт.
{
"error": {
"type": "invalid_request_error",
"code": "request_limit_exceeded",
"param": "tools",
"message": "Request limit exceeded at tools: the number of tools is 129, and the limit is 128. Send fewer tools in one request.",
"limit": { "name": "tools", "max": 128, "actual": 129, "unit": "items" }
}
}Поверхность Messages оборачивает тот же объект верхнеуровневым "type": "error". Тело больше того, что шлюз вообще читает, получает 413 с тем же кодом и limit.name request_body_size; actual в нём нет — остаток тела так и не был прочитан.
Измените запрос — меньше инструментов, текст короче или разбит на части, сжатая история разговора, меньше или меньшие картинки — и отправьте снова. Без изменений он отвергнется так же. Ветвитесь на code и limit.name, а не на тексте сообщения.
Принудительный вызов, которого модель не принимает
Часть моделей не принимает принудительный вызов инструмента: tool_choice: "required" или названную функцию в Chat Completions и Responses, {"type": "any"} или {"type": "tool"} в Messages. Шлюз запрос не переписывает. Он по очереди пробует провайдеров модели и только если ни один из них не принял принудительный вызов, отвечает 422 с кодом tool_choice_unsupported и типом invalid_request_error. Этот ответ приходит раньше любой части ответа модели, поэтому и потоковый вызов получает его обычной JSON-ошибкой.
Сообщение фиксировано, кроме имени модели — это имя, которое вы прислали, уже разрешённое каталогом:
{
"error": {
"type": "invalid_request_error",
"code": "tool_choice_unsupported",
"message": "The model \"<model>\" does not support forcing a tool call (tool_choice \"required\", {\"type\":\"any\"} or a named tool). Send tool_choice \"auto\" or omit tool_choice."
}
}Отправьте tool_choice: "auto" — в Messages {"type": "auto"} — или не задавайте tool_choice, и модель сама решит, вызывать ли инструмент. Перенос того же запроса на другую поверхность не поможет: отказывает модель, а не диалект. Повтор без изменений отвергается так же.
Один 401 на любую беду с ключом
На отсутствующий, искажённый, неизвестный, отозванный и истёкший ключ ответ одинаковый — тот же 401 и та же фраза, — и это решение, а не недоделка. Различать их значило бы превратить шлюз в оракул по ключевому материалу: тот, кто видит разницу между «такого ключа нет» и «этот ключ отозван», читает таблицу ключей платформы по одной догадке за раз.
Поэтому 401 говорит ровно одно: вызов не допущен. Проверьте, что заголовок на месте и записан как bearer-токен, что ключ — это целиком тот секрет, который вы скопировали при выпуске, и что ключ ещё жив. Проверка ключа отвечает на все три вопроса сразу, из браузера и без единой строки кода.
Проверить ключ → Как пишется заголовок →
Когда поток обрывается раньше срока
Отказ, решённый до первого события, приходит обычной JSON-ошибкой со статусом — ровно так же, как ответили бы на неразбитый на события вызов: тот самый конверт, и ничего в потоке. Сбой после начала потока таким быть уже не может: строка статуса ушла раньше. Такой поток просто заканчивается — без завершающего кадра [DONE].
Этим отсутствием всё и сказано, поэтому читать нужно именно его. Клиент, который считает, что «соединение закрылось» значит «ответ дописан», отдаст дальше усечённый ответ, и в полученных им байтах ничто не скажет обратного. Считайте поток, кончившийся до [DONE], неудавшимся вызовом, а не коротким.
Две другие поверхности говорят то же своими событиями. На поверхности Messages сбой приходит событием ошибки этого протокола, и дальше поток кончается без message_stop; на поверхности Responses завершающее событие — response.failed, несущее этот конверт вместо готового тела.
Неудавшийся или отключённый поток может иметь списание. Подтверждённый поставщиком расход рассчитывается, когда он доступен; после доставки части ответа отключение клиента или обрыв поставщика без подтверждённого расхода оплачивается по ограниченным оценкам входа и доставленного текста. Оценка не превышает положительного удержания; билет с нулевым удержанием списывает не больше доступного остатка баланса или пакета. Отмена до доставки ответа или системное завершение без подтверждённого расхода освобождает резерв без списания.
Успешное завершающее событие без итогового расхода проходит асинхронную сверку. Резерв становится доступен для сверки через 15 минут 20 секунд после допуска, срок дела — 24 часа с открытия; сбой обработчика или очередь могут задержать обработку. Правила доказательств и освобождения описаны в расчётах, ожидание расхода — в отмене потока.
Переключение
До модели, как правило, есть больше одного канала. Когда обслуживающий вызов канал отказывает до того, как до вас дошла хоть часть ответа, вызов продолжается на следующем канале той же модели, а не возвращается вам.
Три вида отказа вызов не переносят, а завершают: отказ после того, как до вас дошли первые байты, — потому что нельзя выдать второй ответ посреди того, который вы уже читаете; отменённый вами вызов — потому что вы его больше не ждёте; и вызов, исход которого наверху неизвестен, — потому что повтор мог бы выставить счёт дважды за работу, которая на самом деле удалась.
Поэтому 503 не обещает, что перепробованы все маршруты. Он приходит и тогда, когда ни один канал не подходит под то, о чём просил вызов, — ещё до обращения наверх, — а число каналов, которые переберёт один вызов, ограничено и перебор не является исчерпывающим.