Claude API: ошибки и rate limit — что делать

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

Коды ошибок

400 invalid_request_error — ошибка в запросе: неверное имя модели, пустой список сообщений, нет max_tokens, неправильный формат. Прочитайте текст ошибки — там обычно указано, что не так.
401 authentication_error — нет ключа или он неверный.
403 permission_error — у ключа нет доступа к модели или функции.
404 not_found_error — неверный адрес или модель не существует.
413 request_too_large — слишком большой запрос.
429 rate_limit_error — превышен лимит запросов или токенов в минуту.
500 api_error — внутренняя ошибка на стороне Anthropic.
529 overloaded_error — сервис временно перегружен.

Что такое rate limit

У каждого аккаунта есть лимиты: сколько запросов, входных и выходных токенов можно отправить в минуту. Лимиты растут с уровнем аккаунта, который зависит от суммы пополнений. Текущие лимиты видны в консоли Anthropic в разделе Limits.

Что делать при 429

Посмотрите заголовок retry-after в ответе — он говорит, сколько секунд подождать.
Повторите запрос с экспоненциальной задержкой: 1, 2, 4, 8 секунд, с небольшой случайной добавкой.
Ограничьте количество параллельных запросов.
Если ошибки постоянные — сократите размер запросов или обратитесь за повышением лимита.

SDK Anthropic для Python и TypeScript умеют автоматически повторять запросы при 429 и 5xx — проверьте настройку max_retries.

Что делать при 500 и 529

Это временные проблемы на стороне сервиса. Повторите запрос с задержкой и проверьте status.anthropic.com. Для важных процессов предусмотрите запасной вариант: другую модель или отложенную обработку.

Как снизить вероятность ошибок

кэшируйте ответы на повторяющиеся запросы;
используйте prompt caching для длинного повторяющегося контекста — это ещё и дешевле;
для массовой обработки используйте Message Batches API — пакетные запросы дешевле и не упираются в минутные лимиты;
простые задачи отправляйте в Haiku — см. Claude Haiku: когда хватает лёгкой модели.

Если что-то сломалось

Проверьте status.anthropic.com.
Посмотрите в логах код ошибки и текст.
Проверьте, не менялся ли код, ключ или модель.
Если проблема у вас — откатите изменения. Если у сервиса — включите повторы и подождите.