Ошибки Claude API — лимиты скорости, 400, 500, 529

Ошибки Claude API почти всегда означают одно из нескольких: неверный запрос, превышение лимита, сбой на стороне сервера или перегрузка. Разберём каждый код и как его исправить.

400 — неверный запрос

Ошибка 400 означает проблему в самом запросе: слишком длинный контекст, неверный формат сообщений или несуществующее имя модели. Проверьте, что общий объём входных токенов укладывается в окно модели и что имя модели корректно.

Частая причина — рассинхрон блоков tool_use/tool_result при работе агентов. Убедитесь, что каждому tool_use соответствует tool_result.

429 — превышен лимит скорости

429 значит, что вы превысили лимит запросов или токенов в минуту. В ответе обычно есть заголовок retry-after — подождите указанное время и повторите.

Реализуйте экспоненциальную задержку: при 429 удваивайте паузу перед повтором. Шлюз с пулом из нескольких аккаунтов распределяет нагрузку и снижает частоту 429.

500 и 529 — сбой и перегрузка

500 — внутренняя ошибка сервера, обычно временная: повторите запрос с задержкой. 529 (overloaded_error) означает, что вышестоящий сервис перегружен — нужна более длинная экспоненциальная задержка.

Шлюз с несколькими вышестоящими аккаунтами автоматически переключается на здоровый аккаунт при 500/529, поэтому вы видите эти ошибки заметно реже, чем при прямом обращении.

Логика повторов

Надёжный клиент повторяет запрос на 429/500/529 с экспоненциальной задержкой и не повторяет на 400 (это ошибка в запросе, повтор не поможет).

Если ошибки повторяются на конкретной модели — проверьте имя модели и лимиты, прежде чем винить сервер.

# Пример логики повторов
for attempt in range(5):
    r = call_claude(...)
    if r.status in (429, 500, 529):
        time.sleep(2 ** attempt)   # экспоненциальная задержка
        continue
    break  # 400 не повторяем

FAQ

Что значит ошибка 429 в Claude API?
Превышен лимит запросов/токенов в минуту. Подождите время из retry-after и повторите с экспоненциальной задержкой.

Как исправить ошибку 400?
Проверьте запрос: длину контекста, формат сообщений, имя модели и парность tool_use/tool_result. 400 повторять бессмысленно.

Что делать при 529 overloaded_error?
Вышестоящий сервис перегружен — повторите с длинной экспоненциальной задержкой. Шлюз с пулом аккаунтов снижает частоту этой ошибки.

Снижает ли шлюз количество ошибок?
Да — пул из нескольких вышестоящих аккаунтов позволяет переключаться при 500/529, поэтому вы видите их реже.