Почему Claude API возвращает 429 и как правильно повторять запросы

Короткий ответ: статус 429 означает, что запрос упёрся в применимый лимит или ограничение ускорения. Прочитайте тело ошибки и заголовки, замедлите поток и повторяйте запрос с экспоненциальной задержкой и случайным разбросом. Покупка более высокого тарифа не исправляет плохо устроенную очередь.

Когда этот подход подходит

Материал рассчитан на серверную интеграцию с Claude API. Перед внедрением проверьте, что нужная функция и модель доступны вашему аккаунту. Интерфейс Console и лимиты могут меняться, поэтому названия полей сверяйте с официальной документацией на дату разработки.

Пошаговая настройка

1. Запишите HTTP-статус, тип ошибки, request-id и безопасную часть заголовков лимитов. Не сохраняйте ключ и пользовательский текст без необходимости.
2. Определите, ограничены ли запросы, входные или выходные токены либо другой показатель.
3. Поставьте задачи в очередь и ограничьте параллелизм. Для повторов используйте exponential backoff с jitter и верхней границей попыток.
4. Учитывайте Retry-After, если сервер его возвращает.
5. Для операций с побочными эффектами используйте собственный idempotency key или журнал, чтобы повтор не создал дубль.

Ограничения и применимость

Фактические лимиты зависят от уровня и могут различаться по моделям. Резкий рост нагрузки способен ограничиваться отдельно. 429 не следует путать с ошибкой оплаты, неверным ключом или перегрузкой сервиса — проверяйте тип ответа.

Как проверить результат

Запустите контролируемый нагрузочный тест ниже допустимого порога, затем кратко увеличьте параллелизм. Убедитесь, что очередь замедляется, запросы не теряются, а количество повторов ограничено.

Чего не делать

• Не повторяйте запрос немедленно в бесконечном цикле.
• Не запускайте сотни параллельных повторов после одной ошибки.
• Не меняйте модель вслепую, не прочитав тип ошибки.

Практический вывод

Сначала реализуйте минимальный тест на одном контролируемом примере, добавьте обработку ошибок и журнал технических метаданных. Только после этого подключайте реальные данные и увеличивайте нагрузку. Такой порядок быстрее выявляет ошибки интеграции и не маскирует их убедительным текстом модели.

Официальная документация: https://docs.anthropic.com/en/api/rate-limits