▤ Справочник

Коды ошибок

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

Обновлено ⏱ 7 мин
#ошибки#errors#коды#401#402#429

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

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

типовая ошибка
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

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

КодЗначениеПричинаЧто делать
400Bad RequestНекорректный JSON или параметрыПроверьте тело и обязательные поля
401UnauthorizedНет или неверный ключПроверьте заголовок и ключ cr_…
402Payment RequiredКончился баланс или дневной лимит подпискиПополните ключ в кабинете или на /buy; дневной лимит обновится в новые сутки
403ForbiddenМодель другого семейства («This API key does not include this model family», «Model … is not enabled for this API key») или ключ отключёнВозьмите ключ семейства модели (создаётся в кабинете); если семейство совпадает — в поддержку
404Not FoundНеверный путь или id моделиСверьте endpoint и модель
408Request TimeoutИстёк таймаут запросаУменьшите запрос или повторите
429Too Many RequestsМодель перегружена или IP заблокирован на 10 минут за неверные ключиBackoff и ретрай; проверьте ключ
500Internal Server ErrorВнутренняя ошибка шлюзаПовторите с backoff
502Bad GatewayОшибка upstream-вендораАвторетрай, сработает резерв
503Service UnavailableМодели нет у ключа («This model is not available for this key») или временно недоступноСверьте id с GET /v1/models; если верный — повторите через минуту
529OverloadedМодель временно перегружена («Overloaded: no capacity for this model right now»)Повторите с backoff — клиенты Anthropic делают это сами

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

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

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

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

402 Payment Required
{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "Недостаточно средств на балансе. Пополните счёт."
  }
}
✕
Следите за остатком
Настройте алерт на остаток через Usage Query API — так 402 не остановит прод неожиданно.

#429 — модель перегружена

Своего ограничения на число и параллельность запросов у ключей TKBK нет. 429 приходит, когда модель временно перегружена на всех каналах или IP заблокирован на 10 минут за много неверных ключей подряд. Если в ответе есть retry-after — подождите столько секунд, иначе повторяйте с растущей паузой.

429: IP заблокирован за неверные ключи
HTTP/1.1 429 Too Many Requests
retry-after: 600

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests with invalid API keys from your address. Retry in 600 s."
  }
}
ℹ
429 ≠ 402
429 — временная перегрузка модели или блокировка IP за неверные ключи: подождите (столько секунд, сколько в retry-after, если он есть) и повторите. Кончился баланс или дневной лимит подписки — это 402: поможет пополнение или новые сутки, см. Лимиты.

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

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

#Ретраи и backoff

  1. 1
    Ретраить только 429 и 5xx

    Коды 4xx (кроме 429) — это ваша ошибка, повтор не поможет: исправьте запрос.

  2. 2
    Экспоненциальная задержка

    1с → 2с → 4с → 8с, с небольшим джиттером. Уважайте заголовок retry-after, если он есть.

  3. 3
    Ограничьте число попыток

    3–5 ретраев; дальше отдавайте ошибку выше по стеку и логируйте.

Не помогло?

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