Диагностика · 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 429claude 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 вашего инструмента на него, и конфигурация с этой страницы заработает как написано.