Ошибка 429 Too Many Requests — что делать

Код 429 означает, что запросов слишком много за единицу времени. Это не поломка и не проблема с ключом: сервис просит подождать и повторить.

Чем 429 отличается от соседних ошибок

Их легко перепутать, а лечатся они по-разному.

429 — упёрлись в частоту запросов. Подождать и повторить.

402 — закончились деньги на балансе. Ждать бесполезно, нужно пополнить.

503 — сервис или провайдер модели временно недоступен. Тоже повторять, но интервалы нужны больше.

Первое, что стоит сделать при ошибке, — посмотреть именно код, а не текст. Тексты у разных провайдеров формулируются по-разному, коды стандартны.

Важная оговорка про Zukko: собственного ограничения частоты запросов на шлюзе нет. Если 429 пришёл от самого Zukko, это лимит расходов ключа — код key_daily_limit_reached (дневной лимит, сброс в 00:00 UTC) или key_monthly_limit_reached (месячный). Повторы здесь не помогут: поднимите лимит ключа в кабинете или дождитесь сброса. Все прочие 429 приходят от провайдера модели — именно их и лечат повтором с задержкой.

Как повторять правильно

Немедленный повтор почти всегда даёт второй 429 и делает хуже: вы добавляете нагрузку в момент, когда её и так много.

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

import random, time

for attempt in range(6):
    response = call_api()
    if response.status_code != 429:
        break
    retry_after = response.headers.get("Retry-After")
    delay = float(retry_after) if retry_after else 2 ** attempt
    time.sleep(delay + random.uniform(0, 0.5))

Если сервер прислал заголовок Retry-After, его значение важнее вашей формулы: там указано, сколько ждать на самом деле.

Ограничьте число попыток. Бесконечный цикл повторов превращает временную неприятность в зависший процесс, который вы обнаружите через час.

Почему агенты ловят 429 чаще

Агентные сценарии — Claude Code, автономные пайплайны, параллельная обработка файлов — устроены так, что запросы идут очередями и часто параллельно. Десять одновременных веток дают десятикратную частоту, при этом каждая отдельная ветка выглядит скромно.

Что помогает: ограничить параллелизм явно, а не полагаться на удачу. Пять одновременных запросов вместо двадцати обычно не замедляют работу целиком, потому что упираетесь вы не в свою скорость, а в лимит провайдера модели.

Когда дело не в вас

Если 429 приходит на первом же запросе после долгой паузы, сначала посмотрите код в теле ответа. key_daily_limit_reached или key_monthly_limit_reached — сработал лимит расходов ключа, который задан в кабинете (дневной сбрасывается в 00:00 UTC). Любой другой 429 — лимит на стороне вышестоящего провайдера, и исчерпан он не вами. Если повторы не помогают — стоит написать в поддержку и уточнить, какой именно лимит сработал.