Каждая ошибка API приходит по-русски и в одном формате: машинный error.code, совет error.action, идентификатор запроса request_id (он же в заголовке request-id) и хвост вида [код · req_…] в самом тексте error.message. Хвоста достаточно для разбора: пришлите его в поддержку @Guard_AI_support, и по нему видно статус, код и место сбоя. Полный ключ, промпт и ответ присылать не нужно.
Оболочка зависит от endpoint'а, объект ошибки внутри одинаковый. /v1/messages и count_tokens отвечают в форме Anthropic:
json
{
"type": "error",
"error": {
"type": "billing_error",
"message": "На API-ключе закончился баланс. Пополните ключ в @subscribe_ai_bot и повторите запрос. [insufficient_credit · req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718]",
"code": "insufficient_credit",
"param": null,
"action": "Пополните ключ в @subscribe_ai_bot либо уменьшите максимальный размер ответа."
},
"request_id": "req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718"
}/v1/chat/completions и /v1/responses отвечают в OpenAI-форме без внешнего type:
json
{
"error": {
"message": "На API-ключе закончился баланс. Пополните ключ в @subscribe_ai_bot и повторите запрос. [insufficient_credit · req_3f9a2c1e8b7d4e0fa1b2c3d4e5f60718]",
"type": "billing_error",
"param": null,
"code": "insufficient_credit",
"action": "Пополните ключ в @subscribe_ai_bot либо уменьшите максимальный размер ответа."
},
"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 и время с часовым поясом. - Без полного ключа, промпта и ответа модели.