Каждая ошибка API приходит по-русски и в одном формате: машинный error.code, совет error.action, идентификатор запроса request_id (он же в заголовке request-id) и хвост вида [код · req_…] в самом тексте error.message. Хвоста достаточно для разбора: пришлите его в поддержку @Guard_help, и по нему видно статус, код и место сбоя. Полный ключ, промпт и ответ присылать не нужно.
Оболочка зависит от endpoint'а, объект ошибки внутри одинаковый. /v1/messages и count_tokens отвечают в форме Anthropic:
json
{
"type": "error",
"error": {
"type": "billing_error",
"message": "На API-ключе закончился баланс. Пополните ключ в @guardapi и повторите запрос. [insufficient_credit · req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718]",
"code": "insufficient_credit",
"param": null,
"action": "Пополните ключ в @guardapi либо уменьшите максимальный размер ответа."
},
"request_id": "req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718"
}/v1/chat/completions и /v1/responses отвечают в OpenAI-форме без внешнего type:
json
{
"error": {
"message": "На API-ключе закончился баланс. Пополните ключ в @guardapi и повторите запрос. [insufficient_credit · req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718]",
"type": "billing_error",
"param": null,
"code": "insufficient_credit",
"action": "Пополните ключ в @guardapi либо уменьшите максимальный размер ответа."
},
"request_id": "req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718"
}Ошибки авторизации, API статистики и файлового API кладут тот же объект в detail.error (у авторизации он продублирован и в error). Читайте error, а если его нет — detail.error.
| Поле | Что в нём |
|---|---|
message | текст по-русски; в конце хвост [код · request_id] |
code | стабильный машинный код: по нему ветвится обработка и ищется причина |
type | класс ошибки в терминах Anthropic/OpenAI: invalid_request_error, authentication_error, rate_limit_error, api_error и т. д. |
param | имя поля, если ошибка про конкретное поле, иначе null |
action | один следующий шаг простыми словами |
request_id | идентификатор запроса req_…; тот же в заголовке request-id (у Kimi на Chat/Responses ещё и в x-request-id) |
Если сбой случился после начала SSE, HTTP-статус уже 200, и ошибка приходит кадром с тем же объектом: на /v1/messages и /v1/responses — событие event: error, на /v1/chat/completions — кадр data: {"error": …} и затем data: [DONE]. Обрыва соединения без кадра нет, в том числе у Kimi, Composer и Grok.
text
event: error
data: {"type": "error", "error": {"type": "api_error", "message": "Kimi временно недоступен. Повторите запрос через несколько секунд. [kimi_unavailable · req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718]", "code": "kimi_unavailable", "param": null, "action": "Повторите запрос позже; если ошибка сохраняется, обратитесь в поддержку."}, "request_id": "req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718"}
# на /v1/chat/completions тот же объект приходит как
data: {"error": {...}, "request_id": "req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718"}
data: [DONE]| Код | Значение | Что делать |
|---|---|---|
400 | Некорректный запрос (тело/параметры) | Прочитайте error.code и param; проверьте JSON, имя модели, обязательные поля (max_tokens для Anthropic). |
401 | Неверный, отсутствующий или отозванный ключ | Проверьте ключ; выпустите новый в боте. |
402 | Кредит ключа исчерпан или не хватает на резерв | Пополните активный ключ или уменьшите max_tokens. |
403 | Операция недоступна для ключа или клиента | Прочитайте error.code и ограничения выбранного API; пополнение не исправляет любой 403. |
404 | Endpoint или модель не найдены | Проверьте endpoint (/v1/messages, /v1/chat/completions, /v1/responses) и id модели. |
413 | Тело запроса слишком большое | Уменьшите текст, вложения или число сообщений. |
422 | Параметры не прошли проверку (статистика, файлы) | Исправьте поле из param. |
429 | Rate/capacity или spend limit | Прочитайте error.code и Retry-After: расходный лимит меняется в боте, временный лимит повторяется после задержки. |
500 / 502 | Внутренний сбой или негодный ответ поставщика | Повторите; если повторяется — пришлите хвост [код · req_…] в поддержку. |
503 | Сервис временно недоступен | Повторите с экспоненциальной задержкой; не меняйте модель вслепую. |
504 | Сервис не успел завершить запрос | Повторите; для длинных ответов используйте стриминг. |
error.code | Статус | Что значит | Что делать |
|---|---|---|---|
missing_api_key | 401 | ключ не передан | передайте Authorization: Bearer gd-… или x-api-key |
invalid_api_key | 401 | ключ не найден или скопирован не полностью | скопируйте ключ из бота заново |
api_key_revoked, api_key_expired | 401 / 403 | ключ отозван или его срок истёк | получите новый ключ в боте |
api_key_suspended | 429 | ключ временно заморожен защитой | дождитесь времени из Retry-After |
insufficient_credit | 402 | баланс ключа исчерпан | пополните ключ в боте |
request_reserve_exceeds_credit | 402 | остатка не хватает на резерв максимальной стоимости этого запроса | уменьшите max_tokens или пополните ключ |
daily_spend_limit, hourly_spend_limit, daily_reserve_limit, hourly_reserve_limit | 429 | ваш собственный лимит расхода на ключе | измените лимит в боте или дождитесь окна из Retry-After |
invalid_json, invalid_body_type | 400 | тело не JSON или не объект | исправьте тело запроса |
invalid_request, unsupported_parameter, invalid_parameter | 400 | поле негодное или не поддерживается на этой поверхности; имя в param | уберите или исправьте поле |
messages_required, model_required | 400 | нет обязательного поля | добавьте поле |
model_not_found | 404 | такой модели нет в каталоге | возьмите id из GET /v1/models |
route_not_found, method_not_allowed | 404 / 405 | нет такого адреса или метода | проверьте endpoint и метод |
request_body_too_large | 413 | тело больше допустимого | уменьшите текст или вложения |
context_length_exceeded | 400 | запрос не влезает в окно модели | сократите историю или выберите модель с большим окном |
product_modes_removed | 410 | Режимы удалены; запрос содержит устаревший фильтр mode | Уберите mode из запроса Usage API |
cyber_refusal | 400 / ошибка в потоке | Claude вернул структурированный отказ по кибербезопасности | Измените формулировку или обратитесь в поддержку |
client_key_rate_limit, client_ip_rate_limit | 429 | слишком часто с одного ключа или адреса | повторите через Retry-After |
service_capacity_saturated, standard_capacity_saturated | 429 | все слоты сервиса заняты | повторите через Retry-After |
service_unavailable, upstream_unavailable | 503 | сервис или поставщик временно недоступен | повторите с экспоненциальной задержкой |
stream_service_error, stream_timeout | в потоке | сбой после начала SSE | повторите запрос; при повторении уменьшите контекст |
internal_error | 500 | внутренняя ошибка сервиса | пришлите хвост [код · req_…] в поддержку |
usage_rate_limit, invalid_cursor | 429 / 400 | Слишком частые чтения статистики или негодный курсор | См. Usage API |
Коды Kimi, включая файлы, поиск и семь причин 429, собраны на странице Kimi: ошибки и retry. Ниже — коды Composer и Grok.
У Composer/Grok есть собственные значения error.code. Локально отклонённый новый запрос до обращения к модели не оплачивается. Ошибка уже начатого цикла инструментов или потока может относиться к выполненной и оплаченной части; смотрите историю запроса.
error.code | Статус | Что значит |
|---|---|---|
cursor_parameter_unavailable | 400 | в теле есть поле, которого нет в коротком списке принимаемых |
cursor_client_tools_unavailable | 400 | во входе Responses есть элемент провайдерского инструмента — web_search_call, file_search_call, computer_call и подобные |
cursor_client_tools_invalid | 400 | объявление инструмента негодное: больше 64 штук, дублирующееся или неверное имя, схема больше 256 КиБ |
cursor_client_tool_result_invalid, cursor_client_tool_result_too_large, cursor_client_tool_result_unsupported | 400 | результат инструмента негодный, больше 8 МиБ либо в неподдержанном виде |
cursor_image_input_unavailable | 400 | изображение отправлено в Composer, а он их не принимает |
cursor_image_input_invalid | 400 | картинка не инлайн base64, неподдержанный тип или больше 16 штук |
model_not_found | 404 | id написан с ошибкой |
request_reserve_exceeds_credit | 402 | остатка на ключе не хватает на резерв этого запроса |
cursor_daily_spend_limit, cursor_hourly_spend_limit, cursor_daily_reserve_limit, cursor_hourly_reserve_limit | 429 | ваш собственный лимит расхода; в Retry-After стоит время окна |
client_key_rate_limit | 429 | слишком часто; повторите через короткую паузу |
cursor_key_pause_limit | 429 | Достигнут лимит незавершённых циклов инструментов ключа. Завершите один из них; повтор сам по себе не поможет. |
cursor_model_mismatch | в потоке | наверху ответила другая модель; приходит отдельным событием error |
cursor_unavailable | 503 | временная недоступность; повторяйте с экспоненциальной задержкой |
cursor_run_timeout | 504, в потоке событие error | прогон не уложился в 600 секунд и снят. Прогон оплачен |
cursor_output_limit_exceeded | 502 в обычном ответе | Весь цикл превысил лимит вывода; выполненная часть оплачивается. Поток сохраняет текст и завершается max_tokens / length / response.incomplete. |
cursor_upstream_error | 502, в потоке событие error | прогон не завершился наверху. Если ответ уже начался, он оплачен |
- Хвост
[код · req_…]из текста ошибки или значениеrequest_id— скриншота достаточно. - Endpoint, модель,
streamtrue/false и время с часовым поясом. - Без полного ключа, промпта и ответа модели.
Messages возвращает Anthropic-совместимую оболочку; Chat и Responses — OpenAI-совместимую. Всегда ветвитесь по HTTP-статусу и error.code, а не по переведённому тексту.
json
{
"error": {
"message": "…",
"type": "invalid_request_error",
"code": "unsupported_media",
"param": "messages"
}
}| Группа | Коды |
|---|---|
| Исправить запрос | invalid_json, invalid_request, invalid_parameter, unsupported_media, unsupported_parameter, unsupported_tool, model_not_found |
| Повторить с паузой | client_key_rate_limit, glm_queue_timeout, glm_rate_limit, glm_unavailable |
| Продолжение Responses | response_not_found, response_account_unavailable |
| Нарушенный ответ | glm_invalid_response, glm_invalid_stream, glm_count_unavailable |
Полная таблица действий, включая 10-секундную очередь, Retry-After, вложения и previous_response_id, находится на странице GLM: ошибки и границы.
Ошибки Gemini приходят в той же оболочке, что у остальных семейств: ветвитесь по HTTP-статусу и error.code, а не по тексту. В Chat Completions и Responses error.param называет поле, когда оно известно; в Messages оно всегда null. Запрос, отклонённый до обращения к модели, не оплачивается.
error.code | Статус | Что значит | Что делать |
|---|---|---|---|
invalid_json, invalid_request | 400 | тело не JSON или поле негодное, в том числе уровень размышлений, которого у модели нет; имя поля в param | исправьте тело запроса |
model_not_found | 404 | такой модели нет в каталоге | возьмите id из GET /v1/models: gemini-4-argon или gemini-3.8-flash |
gemini_parameter_unsupported | 400 | поле, которого Gemini не поддерживает; в param — объект с этим полем, для поля верхнего уровня — "request" | уберите поле |
gemini_unsupported_content, gemini_media_unsupported | 400 | Gemini принимает текст, изображения и PDF; аудио, видео и другие файлы нет | уберите вложение или передайте его содержимое текстом |
gemini_invalid_media, gemini_inline_media_required | 400 | вложение негодное: ссылка не https или с логином, повреждённый base64; в Messages источник не base64 и не ссылка; ссылка на картинку в результате функции | передайте вложение base64 или открытой ссылкой https; в результате функции — base64 |
gemini_tool_result_media_unsupported | 400 | в результате функции вложение не PNG, JPEG, WEBP или PDF | передайте результат текстом или в одном из этих форматов |
gemini_tool_unsupported | 400 | инструмент, кроме функций и поиска, например отдельная загрузка страниц web_fetch | оставьте функции и встроенный поиск |
gemini_search_options_unsupported | 400 | настройка поиска, которой у Gemini нет: список доменов, max_tool_calls и другие поля | оставьте у поиска только type, name и max_uses |
gemini_tool_choice_unsupported | 400 | обязательный вызов или вызов конкретной функции вместе с поиском, либо обязательный вызов без функций | разделите запрос или уберите обязательный вызов |
gemini_strict_tools_unsupported, gemini_parallel_limit_unsupported | 400 | strict: true у функции или запрет параллельных вызовов | уберите поле |
invalid_tool_structure | 400 | одинаковые имена функций, tool_choice с функцией не из списка, аргументы вызова не JSON или вызов функции не в сообщении ассистента | исправьте список функций или историю вызовов |
gemini_thinking_unsupported | 400 | форма размышлений, которой Gemini не принимает: budget_tokens, другие поля thinking или reasoning, reasoning.summary кроме "auto" | используйте thinking: {"type": "adaptive"}, а уровень задайте полем уровня из страницы модели |
invalid_request с param: "background" | 400 | фоновое выполнение Responses не поддерживается | уберите background |
gemini_history_required | 400 | поле conversation Gemini не принимает | передайте историю в input или продолжайте через previous_response_id |
gemini_history_mismatch, gemini_native_history_invalid, gemini_history_not_found | 400 / 404 | история не совпадает с сохранённой, сохранённая история вызова функции не подходит к запросу, или ответ для previous_response_id не найден либо старше 30 дней | отправьте историю диалога целиком |
gemini_rejected | 400 | Gemini не принял запрос | проверьте поля запроса и историю диалога |
policy_refusal | 400 | Google отклонил запрос или ответ по своим правилам: блокировка, безопасность, совпадение с защищённым текстом. Этот код приходит только без потока: в потоке до начала ответа приходит 502 gemini_invalid_stream, после начала — кадр gemini_stream_error | измените формулировку |
api_key_paused | 403 | ключ или это семейство приостановлены в настройках ключа | возобновите ключ или включите семейство в настройках ключа в личном кабинете |
insufficient_credit, request_reserve_exceeds_credit | 402 | баланс ключа исчерпан или его не хватает на резерв запроса | пополните ключ в боте или уменьшите max_tokens |
client_key_rate_limit, gemini_rate_limited | 429 | слишком часто с одного ключа или Gemini временно ограничил число запросов | повторите через Retry-After |
gemini_quota_exhausted | 429 | квота этой модели исчерпана | повторите после сброса лимита (время в Retry-After) или выберите другую модель |
gemini_unavailable, service_unavailable | 503 | свободного аккаунта сейчас нет или Gemini временно недоступен | повторите с экспоненциальной задержкой |
gemini_not_connected | 503 | модели Gemini пока не подключены | повторите позже или выберите модель другого семейства |
gemini_settings_unavailable, gemini_billing_unavailable, gemini_history_unavailable | 503 | временно недоступны настройки, учёт или хранилище истории | повторите через несколько секунд |
gemini_invalid_response, gemini_invalid_stream, gemini_invalid_usage, gemini_incomplete_response, gemini_incomplete_stream, gemini_empty_response, gemini_generation_failed, gemini_unsupported_output, gemini_partial_function_call_unsupported, gemini_invalid_json_value, gemini_upstream_error | 502 | ответ Gemini пришёл неполным или негодным | новый запрос допустим, если приложение исключает двойное выполнение побочного действия |
gemini_stream_error | в потоке | поток прерван после начала ответа. Внутренние сбои разбора потока Google (gemini_stream_event_too_large, gemini_stream_already_finished) приходят этим кадром, а до начала ответа — как 502 gemini_invalid_stream | доставленная часть остаётся у клиента; повторите запрос |
Ошибки Muse приходят в той же оболочке, что у остальных семейств: ветвитесь по HTTP-статусу и error.code, а не по тексту. В Chat Completions и Responses error.param называет поле, когда оно известно; в Messages оно всегда null. Запрос, отклонённый до обращения к модели, не оплачивается.
error.code | Статус | Что значит | Что делать |
|---|---|---|---|
invalid_json, invalid_request | 400 | тело не JSON, поле негодное или Meta отклонила параметры запроса | исправьте тело запроса |
invalid_parameter, invalid_messages, invalid_input, invalid_stream, invalid_stream_options, invalid_tools, invalid_previous_response_id | 400 | значение поля негодное, например уровень none или store не логическое; имя поля в param | исправьте поле |
unsupported_parameter | 400 | поле, которого Muse не поддерживает: отдельный web_fetch, ограничение доменов поиска, фоновое выполнение Responses, подсчёт токенов с previous_response_id | уберите поле; для подсчёта передайте историю в input |
unsupported_media | 400 | Muse принимает текст, изображения и PDF; видео, аудио и другие файлы нет | уберите вложение или передайте его содержимое текстом |
unsupported_tool | 400 | инструменты MCP на стороне поставщика через Guard недоступны | уберите инструмент или исполняйте его как клиентскую функцию |
model_not_found | 404 | такой модели нет в каталоге | возьмите id из GET /v1/models |
response_not_found | 404 | ответа для previous_response_id нет у этого ключа или он создан с store: false | передайте историю в input |
response_account_unavailable | 409 | продолжение временно недоступно на аккаунте, где сохранён ответ | повторите позже или передайте историю в input |
api_key_paused | 403 | ключ или это семейство приостановлены в настройках ключа | возобновите ключ или включите семейство в настройках ключа в личном кабинете |
insufficient_credit, request_reserve_exceeds_credit | 402 | баланс ключа исчерпан или его не хватает на резерв запроса | пополните ключ в боте или уменьшите max_tokens |
client_key_rate_limit, muse_rate_limit, muse_queue_timeout | 429 | слишком часто с одного ключа или все слоты Muse заняты | повторите через Retry-After |
muse_unavailable, muse_pool_unavailable | 503 | Muse временно недоступен | повторите с экспоненциальной задержкой |
muse_not_connected | 503 | модели Muse пока не подключены | повторите позже или выберите модель другого семейства |
muse_prompt_unavailable, muse_state_unavailable, muse_billing_unavailable | 503 | временно недоступны настройки, состояние ответа или учёт | повторите через несколько секунд |
muse_prompt_model_invalid | 503 | применённая настройка Muse содержит недопустимое изменение запроса | не повторяйте то же тело циклически; передайте код в поддержку |
muse_invalid_response, muse_invalid_stream | 502 | ответ Meta пришёл неполным | новый запрос допустим, если приложение исключает двойное выполнение побочного действия |
muse_stream_error | в потоке | поток прерван после начала ответа | доставленная часть остаётся у клиента; повторите запрос |