Диагностика · Claude Code

Claude Code API Error 429 (rate_limit_error) — причина и решение

Claude Code печатает API Error: 429 rate_limit_error, когда достигнут потолок частоты или параллелизма аккаунта. Почему его выбивают параллельные агенты на моделях GPT и Gemini и как это чинится.

Что вы видите

API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"Rate limit reached. Please retry shortly."}}

Почему возникает

  • Превышен потолок частоты или параллелизма аккаунта, которому принадлежит ключ. Claude Code отправляет запросы к GPT и Gemini через Messages API, и этот эндпоинт сообщает о потолке как 429 rate_limit_error.
  • Несколько сессий Claude Code или субагентов работают параллельно на одном ключе — каждая отправляет запрос на каждом ходе, поэтому всплески накапливаются быстрее, чем кажется.
  • На моделях google/* текст тела приходит со стороны Gemini — Resource has been exhausted. Please retry later., — а статус и error.type остаются теми же.
  • Ретраи, наложенные поверх всплеска, вызвавшего первый 429, раздувают его вместо того, чтобы дать ему рассосаться.

Что делать

  • Немного подождите — Claude Code ретраит автоматически и учитывает Retry-After. Если ошибка повторяется, уменьшите число сессий на одном ключе.
  • Запускайте меньше субагентов и параллельных сессий одновременно — именно параллельные запросы первыми упираются в потолок.
  • Не путайте это с HTTP 402 — то пустой предоплаченный баланс. 429 — повторяемая пропускная способность. Для 402 пополните баланс; для 429 читайте Retry-After.
  • Если вам стабильно нужно больше пропускной способности, чем позволяет аккаунт, ограничьте параллелизм в своих скриптах и напишите в поддержку. Не ретрайте 402 как 429.

Похожие запросы

  • claude code api error 429
  • claude code rate limit error

Вопросы и ответы

API Error 429 в Claude Code означает, что предоплаченный баланс пуст?+
Нет. 429 — пропускная способность. Пустой предоплаченный баланс — HTTP 402. На 429 читайте Retry-After. На 402 пополните баланс.
Ретраит ли Claude Code 429 сам?+
Да — он отступает и повторяет автоматически. Если ошибка держится, окно пополняется быстрее, чем расходуется, — обычно параллельными сессиями на том же ключе.
Влияет ли выбранная в Claude Code модель на 429?+
Статус и error.type одинаковы для моделей openai/* и google/*. Отличается только текст: модели GPT пишут Rate limit reached. Please retry shortly., модели Gemini — Resource has been exhausted. Please retry later.

Пропустите сломанную настройку

apiToken.sale отдаёт модели GPT и Gemini через OpenAI-совместимые эндпоинты, Messages (формат Anthropic) и нативный Gemini — стандартные SDK, один ключ, один предоплаченный баланс. Направьте base URL вашего инструмента на него, и конфигурация с этой страницы заработает как написано.