Ошибка 429 Too Many Requests означает, что вы отправили больше запросов или токенов, чем позволяет ваш лимит в текущем временном окне. Ее возвращают OpenAI, Anthropic и OpenRouter, и обычно она проявляется при первом запуске приложения под реальной нагрузкой или при распределении пакетного задания по нескольким воркерам.
Большинство людей сразу пытаются настроить повторные попытки (retry), но при настройках по умолчанию этого часто недостаточно. Когда мы запустили пакет из 60 промптов через Python SDK OpenAI против лимита на количество запросов в минуту, 23 запроса все равно завершились ошибкой после повторных попыток SDK. Временное окно сбрасывалось через 4–8 секунд после того, как SDK сдавался на каждом из них.
В этом руководстве мы разберем реальную ошибку 429, прочитаем ее заголовки и устраним ее тремя способами: повторная попытка в момент сброса, указанный в ошибке; перенаправление избыточного трафика на резервную модель; и переключение на другого провайдера для той же модели. Мы протестировали каждый пример на API OpenRouter, и под каждым блоком кода приведен полученный нами результат.
Кратко
- Ошибка 429 означает, что вы исчерпали лимит в текущем окне. В OpenRouter поле error.metadata.limit_source подсказывает, чей именно лимит был превышен.
Ошибка 429 означает, что вы исчерпали лимит в текущем окне. В OpenRouter поле error.metadata.limit_source подсказывает, чей именно лимит был превышен.
- При настройках по умолчанию Python SDK OpenAI повторял каждую ошибку 429 дважды и сдавался примерно через 2 секунды. При ограничении на количество запросов в минуту 23 из 60 запросов в нашем пакете все равно завершились ошибкой.
При настройках по умолчанию Python SDK OpenAI повторял каждую ошибку 429 дважды и сдавался примерно через 2 секунды. При ограничении на количество запросов в минуту 23 из 60 запросов в нашем пакете все равно завершились ошибкой.
- Повторный запрос, ожидающий заголовок Retry-After или X-RateLimit-Reset, успешно завершил все 60 запросов в каждом запуске: за 89–92 секунды на Python и за 106–218 секунд на TypeScript.
Повторный запрос, ожидающий заголовок Retry-After или X-RateLimit-Reset, успешно завершил все 60 запросов в каждом запуске: за 89–92 секунды на Python и за 106–218 секунд на TypeScript.
- Резервный вариант с другими моделями завершил все 60 запросов за 13 секунд и стоил $0.000066 без какого-либо ожидания.
Резервный вариант с другими моделями завершил все 60 запросов за 13 секунд и стоил $0.000066 без какого-либо ожидания.
- Привязка к одному провайдеру с отключенным отказоустойчивым переключением приводила к сбоям до 32 из 150 запросов за запуск. С включенным отказоустойчивым переключением все 150 запросов успешно выполнялись в каждом запуске.
Привязка к одному провайдеру с отключенным отказоустойчивым переключением приводила к сбоям до 32 из 150 запросов за запуск. С включенным отказоустойчивым переключением все 150 запросов успешно выполнялись в каждом запуске.
Как выглядит ошибка лимита скорости 429?
Мы отправили 40 запросов одновременно на poolside/laguna-s-2.1:free — бесплатную модель с лимитом в 20 запросов в минуту. Тридцать восемь запросов выполнились успешно, а два вернулись со статусом 429 от провайдера, обслуживающего модель:
Ошибка 429 из-за нашего собственного лимита бесплатного тарифа имеет другое значение limit_source. Вот пример из отдельного запуска:
Заголовки содержат необходимые вам числа. X-RateLimit-Limit — это максимальный лимит, X-RateLimit-Remaining — оставшееся количество, а X-RateLimit-Reset — самое раннее время, когда повторная попытка может завершиться успехом, в виде временной метки Unix в миллисекундах. Тело ответа добавляет limit_source, которое указывает, чей лимит был превышен, и remedy_hint, написанное для людей, читающих логи. В своем коде делайте ветвление по limit_source, а не по тексту подсказки.
OpenAI и Anthropic передают ту же информацию под другими названиями. OpenAI’sx-ratelimit-reset-requests — это длительность, например 1s, а оба провайдера могут передавать retry-after в виде числа секунд.
Почему ограничения скорости срабатывают при разном количестве запросов?
Тридцать восемь из 40 запросов прошли сквозь лимит в 20 запросов. Ограничитель может принимать запросы, поступающие одновременно, до того, как счетчик обновится, и большинство ограничителей не сбрасываются строго в начале каждой минуты. Anthropic использует «токенное ведро» (token bucket), которое пополняется непрерывно. OpenAI can return a 429 с кодом slow_down, когда ваш трафик нарастает слишком быстро, даже если вы находитесь в рамках лимитов на количество запросов в минуту.
Чтобы посмотреть, как работает подсчет лимитов для нашей бесплатной модели, мы отправили еще 161 запрос по разным схемам. Вот три из них:
Из этого выяснились две вещи. Более 20 запросов успешно проходили в каждую минуту, которую мы тестировали, поэтому воспринимайте число 20 как точку, в которой могут начать появляться ошибки 429, а не как точный счетчик. Когда мы столкнулись с этим на poolside/laguna-s-2.1:free за 58 секунд до конца окна, пять запросов к minimax/minimax-m3.1-flash:free прошли сразу, в то время как Laguna оставалась заблокированной. Однако это не означает, что лимит установлен на каждую модель в отдельности. OpenRouter применяет единый поминутный ограничитель ко всем бесплатным моделям на аккаунте, поэтому запрос к другой бесплатной модели может получить ту же ошибку 429.
Шаг 1: Узнайте, чей лимит вы превысили
Ожидание исправляет ошибку 429 только тогда, когда лимит сбрасывается по расписанию, поэтому перед тем, как выбрать способ устранения, проверьте limit_source:
Ошибка 429 выше по цепочке (upstream) означает, что у провайдера, обслуживающего модель, закончились ресурсы. Провайдеры не сообщают, когда эти ресурсы освободятся, поэтому в наших запусках эти ошибки не содержали заголовка сброса. Бесплатный вариант модели Gemma 4 31B вернул следующее:
Тот же запрос с платным вариантом в качестве резервного использовал ресурсы другого провайдера и успешно выполнился на DeepInfra за $0.0000037.
Некоторые ошибки, похожие на ограничения скорости, связаны с финансами. И OpenAI, и Anthropic возвращают код 429 при достижении месячного лимита расходов, и повторные попытки не помогут, пока этот лимит не сбросится. В OpenRouter проблемы с кредитами возвращаются как код 402.
Шаг 2: Повторите запрос в момент сброса, указанный в ошибке
Python SDK для OpenAI и Anthropic по умолчанию повторяют запрос с ошибкой 429 дважды с короткой экспоненциальной задержкой (backoff), которая начинается с 0,5 секунды и никогда не превышает 8. Они следуют заголовку Retry-After, когда сервер его отправляет.
Наша ошибка 429 на бесплатном тарифе вместо этого отправляет X-RateLimit-Reset, который SDK не читают, поэтому обе повторные попытки попали в то же самое заполненное окно. Вот пакет из 60 промптов (по 10 за раз), отправленный через OpenAI SDK (openai 3.26.1) с настройками по умолчанию:
SDK отправил 112 HTTP-запросов для 60 промптов, и 23 из них все равно завершились ошибкой. Увеличение max_retries в конечном итоге позволило бы пройти, но только за счет отправки запроса в забитое окно каждые 8 секунд, а в документации OpenAI отмечается, что неудачные запросы все равно учитываются в вашем лимите на количество запросов в минуту. Более грамотный повторный запрос ждет до времени, указанного сервером. Чтобы выполнить все 60 промптов, используйте аккаунт, у которого осталось как минимум 60 запросов к бесплатным моделям на сегодня, поскольку аккаунты, не купившие 10 кредитов, получают 50 запросов в день:
Все 60 запросов завершились, но выполнение пакета заняло 89 секунд вместо 12. При таком подходе ничто не падает, и каждый запрос, достигающий лимита, ожидает окончания окна.
retry_delay сначала проверяет Retry-After, поскольку это прямое указание сервера, в то время как X-RateLimit-Reset отмечает лишь момент обновления окна. Случайная задержка от 1 до 5 секунд мешает 10 воркерам повторять попытки в один и тот же момент и сразу же заполнять новое окно.
Тем не менее, четыре запроса в этом запуске повторили попытку после того, как новое окно уже заполнилось, поэтому им пришлось ждать во второй раз. Если вы оборачиваете вызов SDK в подобный цикл, установите max_retries=0 на клиенте, иначе каждая ваша попытка превратится в три запроса.
Такой же повторный запрос на TypeScript
retry.ts следует тому же порядку: Retry-After, затем X-RateLimit-Reset, затем задержка. Он использует встроенную функцию fetch, поэтому ему не нужны сторонние пакеты. Мы запускали его на Node 24 с помощью npx tsx retry.ts:
Общее время зависит от того, в какой момент окна запускается пакетная обработка и насколько загружен провайдер модели. Наши два запуска на TypeScript заняли 218 и 106 секунд, а два запуска на Python — 92 и 89 секунд. Все четыре успешно завершили каждый запрос.
Шаг 3: Перенаправление избыточных запросов на резервную модель
Если ответ от второй модели является приемлемым, вам вообще не нужно ждать. Ограничение скорости провайдера применяется к одной модели у одного провайдера, поэтому другая модель использует отдельные ресурсы. Исключением является лимит бесплатного уровня, поскольку все модели с тегом :free в вашей учетной записи используют его совместно. С помощью параметра models мы пробуем каждую модель по очереди и переходим к следующей при любой ошибке, включая 429, прежде чем что-либо дойдет до вашего кода:
Бесплатная модель обслужила 52 запроса, а платная — остальные 8. Ни один запрос не ожидал, и вы платите только за платные. Поле model в ответе фиксирует, какая именно модель ответила, и именно за эту модель выставляется счет.
Выберите резервную модель, у которой есть собственные ресурсы. Все модели :free в вашей учетной записи используют общий лимит для бесплатных моделей, поэтому другая бесплатная модель не является надежным резервным вариантом, когда причиной является именно этот лимит. Бесплатные модели также часто исчерпывают ресурсы провайдера, поэтому платная резервная модель — более надежный выбор.
Вот три запуска одного и того же пакета для сравнения:
Если задачу можно отложить, повторите попытку после сброса лимита. Если нет, и ответ второй модели достаточно хорош, добавьте резервный вариант.
Шаг 4: Позвольте другому провайдеру обслуживать ту же модель
Шаги 2 и 3 решают проблему с лимитом бесплатных моделей. Платные модели сталкиваются с другим типом ограничений: пропускной способностью провайдера, который их обслуживает. Большинство моделей на OpenRouter обслуживаются несколькими провайдерами, каждый из которых имеет свои ограничения скорости. Когда один провайдер возвращает ошибку 429, мы повторяем запрос через следующего провайдера, прежде чем ошибка дойдет до вас. Эта функция включена по умолчанию.
Мы отправили 300 запросов к google/gemma-4-31b-it по 50 штук за раз и проверили список provider_responses в записи GET /api/v1/generation каждого запроса, где показаны все провайдеры, которых мы пробовали:
Распределив нагрузку между шестью провайдерами, ни один запрос не потребовал повторной попытки. Затем мы закрепили ту же модель за Crusoe с помощью “provider”: {“order”: [“crusoe”]} и отправили 150 запросов по 50 штук. Вот один из запусков с включенными резервными вариантами:
Crusoe ограничил скорость для 79 запросов, CoreWeave ответил на все 79, и клиент получил 150 успешных ответов. Мы повторили закрепленный запуск несколько раз с выключенным и включенным параметром allow_fallbacks:
Ресурсы Crusoe менялись от минуты к минуте, поэтому количество сбоев при выключенных резервных вариантах варьировалось от нуля до 32. При включенных резервных вариантах Crusoe ограничивал скорость для 21, 41 и 79 запросов в трех запусках, и клиент не увидел ни одного из них. Любое ограничение списка провайдеров, которые могут обслуживать запрос, оставляет меньше ресурсов для поглощения всплесков нагрузки. Если вы все еще видите ошибки 429 от провайдеров на OpenRouter, проверьте параметры: allow_fallbacks: false, короткий список only или жесткий max_price. Чтобы предпочесть одного провайдера, не теряя возможности переключения при сбоях, установите order и оставьте allow_fallbacks по умолчанию.
Тот же всплеск из 300 запросов к anthropic/claude-haiku-5.5 и openai/gpt-6-luna не имел ни одной неудачной попытки. Когда у API закрытой модели заканчиваются ресурсы, ошибка обычно имеет код 529, а не 429, что описано в руководстве по перегрузке Claude 529.
Как вообще избежать достижения лимитов скорости?
Приведенные выше исправления помогают справиться с ошибкой 429 после того, как она произошла. Эти привычки помогут снизить вероятность их возникновения:
- Ограничивайте параллелизм в соответствии с лимитами. Именно параллелизм привел к превышению лимита в нашем первом тесте. Регулировка запросов чуть ниже лимита отнимает меньше времени, чем ожидание окончания полного окна после ошибки 429.
Ограничивайте параллелизм в соответствии с лимитами. Именно параллелизм привел к превышению лимита в нашем первом тесте. Регулировка запросов чуть ниже лимита отнимает меньше времени, чем ожидание окончания полного окна после ошибки 429.
- Устанавливайте max_tokens близко к ожидаемой длине ответа. OpenAI учитывает max_tokens в вашем лимите токенов в минуту, поэтому завышенное значение исчерпывает лимит быстрее, чем сами ответы.
Устанавливайте max_tokens близко к ожидаемой длине ответа. OpenAI учитывает max_tokens в вашем лимите токенов в минуту, поэтому завышенное значение исчерпывает лимит быстрее, чем сами ответы.
- Проверяйте свой ключ перед выполнением большой задачи. GET /api/v1/key показывает ежедневный счетчик бесплатных моделей. После наших запусков он показывал {‘used’: 585, ‘limit’: 1000, ‘remaining’: 415}. Дневной лимит составляет 50 запросов к бесплатным моделям, пока вы не купили как минимум 10 кредитов, и 1000 после этого.
Проверяйте свой ключ перед выполнением большой задачи. GET /api/v1/key показывает ежедневный счетчик бесплатных моделей. После наших запусков он показывал {‘used’: 585, ‘limit’: 1000, ‘remaining’: 415}. Дневной лимит составляет 50 запросов к бесплатным моделям, пока вы не купили как минимум 10 кредитов, и 1000 после этого.
- Используйте платные варианты в продакшене. Лимит 20 запросов в минуту применяется только к моделям :free.
Используйте платные варианты в продакшене. Лимит 20 запросов в минуту применяется только к моделям :free.
Часто задаваемые вопросы
Как увеличить лимит скорости API OpenAI?
OpenAI автоматически повышает ваши лимиты по мере того, как общие покупки кредитов вашей организацией проходят пороги уровней использования. Вы можете увидеть свои текущие лимиты в разделе Settings > Organization > Limits на панели управления OpenAI. Через OpenRouter маршрутизация провайдеров распределяет трафик модели между всеми провайдерами, которые ее обслуживают, поэтому лимит одного провайдера не ограничивает вас.
Почему Claude выдает сообщение “rate limit reached”?
В API Claude это означает, что ваша организация исчерпала лимит запросов или токенов в минуту для этой модели, а заголовок retry-after указывает, сколько секунд нужно подождать. Если ошибка 429 вызвана вашим ежемесячным лимитом расходов, заголовка retry-after нет, и повторные попытки не помогут, пока доступ не будет возобновлен. В Claude Code при наличии подписки это сообщение обычно означает достижение лимита использования плана. См. Hit your Claude Code usage limit?.
Помогают ли дополнительные ключи API обойти лимиты скорости?
Нет. На OpenRouter дополнительные ключи API или учетные записи не меняют ваши лимиты скорости, потому что мы управляем ресурсами глобально. Лимиты провайдера применяются к каждой модели, поэтому резервная модель работает, но все модели :free в вашей учетной записи используют один общий лимит бесплатного уровня. При использовании собственного ключа (BYOK) запросы, использующие ваш ключ провайдера, учитываются в ваших лимитах у этого провайдера.
Retry-After указан в секундах или миллисекундах?
В секундах или в формате даты HTTP. Наш заголовок X-RateLimit-Reset отличается. Это метка времени Unix в миллисекундах. Функция retry_delay на шаге 2 обрабатывает все три формы.
Следующие шаги
- Лимиты: лимиты бесплатных моделей, заголовки X-RateLimit-* и способы обработки ошибок 402 и 429.
Лимиты: лимиты бесплатных моделей, заголовки X-RateLimit-* и способы обработки ошибок 402 и 429.
- Маршрутизация провайдеров: order, allow_fallbacks, only и сортировка.
Маршрутизация провайдеров: order, allow_fallbacks, only и сортировка.
- Резервные модели: параметр models и то, как тарифицируются резервные запросы.
Резервные модели: параметр models и то, как тарифицируются резервные запросы.
- Сравнение бесплатных API LLM: лимиты бесплатного уровня у разных провайдеров.
Сравнение бесплатных API LLM: лимиты бесплатного уровня у разных провайдеров.
