▤ Справочник

Коды ошибок

HTTP-коды 400–503: причина и решение, примеры JSON-ошибок. Отдельно 402 (кончился баланс) и 429 (rate limit / дневной лимит).

Обновлено 20 июл. 2026 г.⏱ 7 мин

#ошибки#errors#коды#401#402#429

Шлюз отдаёт стандартные HTTP-коды и JSON-ошибку в формате того вендора, к которому шёл запрос. Ниже — что означает каждый код и как реагировать.

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

типовая ошибка

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

#Таблица кодов

Код	Значение	Причина	Что делать
400	Bad Request	Некорректный JSON или параметры	Проверьте тело и обязательные поля
401	Unauthorized	Нет или неверный ключ	Проверьте заголовок и ключ `cr_…`
402	Payment Required	Кончился баланс	Пополните счёт у @nukind
403	Forbidden	Ключ отключён / доступ запрещён	Обратитесь в поддержку
404	Not Found	Неверный путь или id модели	Сверьте endpoint и модель
408	Request Timeout	Истёк таймаут запроса	Уменьшите запрос или повторите
429	Too Many Requests	Rate limit или дневной лимит	Backoff и ретрай
500	Internal Server Error	Внутренняя ошибка шлюза	Повторите с backoff
502	Bad Gateway	Ошибка upstream-вендора	Авторетрай, сработает резерв
503	Service Unavailable	Перегрузка / временно недоступно	Backoff, повторите позже

#401 — неверный ключ

⚠

Проверьте заголовок

Ключ должен идти целиком: Authorization: Bearer cr_… или x-api-key: cr_…. Частая причина — обрезанный при копировании ключ или лишние пробелы.

#402 — кончился баланс

Код 402 означает, что на счёте недостаточно средств для выполнения запроса. Пополните баланс — списание идёт по факту, по upstream-токенам.

402 Payment Required

{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "Недостаточно средств на балансе. Пополните счёт."
  }
}

Следите за остатком

Настройте алерт на остаток через Usage Query API — так 402 не остановит прод неожиданно.

#429 — rate limit и дневной лимит

Код 429 возвращается в двух случаях: превышен RPM (~30 запросов/мин) или исчерпан дневной лимит ключа. В ответе есть заголовок retry-after с числом секунд до повтора.

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
retry-after: 12

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Превышен лимит запросов. Повторите через 12 секунд."
  }
}

ℹ

Rate limit ≠ дневной лимит

Если retry-after — секунды, это RPM: подождите и повторите. Если лимит исчерпан на сутки — расход упрётся в дневной лимит ключа до следующего дня, см. Лимиты.

#5xx — сбой шлюза или upstream

500 — внутренняя ошибка: повторите запрос с экспоненциальным backoff.
502 — ошибка upstream-вендора: обычно лечится автоматическим переключением на резерв.
503 — временная перегрузка: сделайте паузу и повторите.

#Ретраи и backoff

1
Ретраить только 429 и 5xx
Коды 4xx (кроме 429) — это ваша ошибка, повтор не поможет: исправьте запрос.
2
Экспоненциальная задержка
1с → 2с → 4с → 8с, с небольшим джиттером. Уважайте заголовок retry-after, если он есть.
3
Ограничьте число попыток
3–5 ретраев; дальше отдавайте ошибку выше по стеку и логируйте.

Лимиты и квоты

RPM, дневной и оконный лимиты.

Usage Query API

Мониторьте баланс и не ловите `402`.

Статус и надёжность

Резерв вне РФ и автопереключение.

Не помогло?

Напишите в Telegram — поможем с настройкой и подберём тариф. Или вернитесь ко всем разделам документации.

@nukind Все доки