Коды ошибок
HTTP-коды 400–503: причина и решение, примеры JSON-ошибок. Отдельно 402 (кончился баланс или дневной лимит подписки) и 429 (модель перегружена).
Шлюз отдаёт стандартные HTTP-коды и JSON-ошибку в формате того вендора, к которому шёл запрос. Ниже — что означает каждый код и как реагировать.
#Формат ошибки
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
}#Таблица кодов
| Код | Значение | Причина | Что делать |
|---|---|---|---|
| 400 | Bad Request | Некорректный JSON или параметры | Проверьте тело и обязательные поля |
| 401 | Unauthorized | Нет или неверный ключ | Проверьте заголовок и ключ cr_… |
| 402 | Payment Required | Кончился баланс или дневной лимит подписки | Пополните ключ в кабинете или на /buy; дневной лимит обновится в новые сутки |
| 403 | Forbidden | Модель другого семейства («This API key does not include this model family», «Model … is not enabled for this API key») или ключ отключён | Возьмите ключ семейства модели (создаётся в кабинете); если семейство совпадает — в поддержку |
| 404 | Not Found | Неверный путь или id модели | Сверьте endpoint и модель |
| 408 | Request Timeout | Истёк таймаут запроса | Уменьшите запрос или повторите |
| 429 | Too Many Requests | Модель перегружена или IP заблокирован на 10 минут за неверные ключи | Backoff и ретрай; проверьте ключ |
| 500 | Internal Server Error | Внутренняя ошибка шлюза | Повторите с backoff |
| 502 | Bad Gateway | Ошибка upstream-вендора | Авторетрай, сработает резерв |
| 503 | Service Unavailable | Модели нет у ключа («This model is not available for this key») или временно недоступно | Сверьте id с GET /v1/models; если верный — повторите через минуту |
| 529 | Overloaded | Модель временно перегружена («Overloaded: no capacity for this model right now») | Повторите с backoff — клиенты Anthropic делают это сами |
#401 — неверный ключ
Authorization: Bearer cr_… или x-api-key: cr_…. Частая причина — обрезанный при копировании ключ или лишние пробелы.#402 — кончился баланс
Код 402 означает, что на счёте недостаточно средств для выполнения запроса. Пополните баланс — списание идёт по факту, по upstream-токенам. У ключа-подписки 402 приходит и тогда, когда исчерпан дневной лимит: он обновится в начале следующих суток.
{
"type": "error",
"error": {
"type": "insufficient_balance",
"message": "Недостаточно средств на балансе. Пополните счёт."
}
}402 не остановит прод неожиданно.#429 — модель перегружена
Своего ограничения на число и параллельность запросов у ключей TKBK нет. 429 приходит, когда модель временно перегружена на всех каналах или IP заблокирован на 10 минут за много неверных ключей подряд. Если в ответе есть retry-after — подождите столько секунд, иначе повторяйте с растущей паузой.
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 — временная перегрузка модели или блокировка IP за неверные ключи: подождите (столько секунд, сколько в retry-after, если он есть) и повторите. Кончился баланс или дневной лимит подписки — это 402: поможет пополнение или новые сутки, см. Лимиты.#5xx — сбой шлюза или upstream
500— внутренняя ошибка: повторите запрос с экспоненциальным backoff.502— ошибка upstream-вендора: обычно лечится автоматическим переключением на резерв.503— временная перегрузка: сделайте паузу и повторите.
#Ретраи и backoff
- 1Ретраить только 429 и 5xx
Коды
4xx(кроме429) — это ваша ошибка, повтор не поможет: исправьте запрос. - 2Экспоненциальная задержка
1с → 2с → 4с → 8с, с небольшим джиттером. Уважайте заголовок
retry-after, если он есть. - 3Ограничьте число попыток
3–5 ретраев; дальше отдавайте ошибку выше по стеку и логируйте.