Примечание автора: столкнувшись с 429, не спешите сразу менять модель. В этой статье мы за 3 шага разберёмся, откуда пришло ограничение — от upstream-провайдера, от шлюза или из-за бесплатного тарифа, — а также покажем, как настроить экспоненциальный backoff, обработку Retry-After и переключение при сбоях.
Когда ночью гоняешь пакетные задачи, в логах внезапно появляется целый экран 429 Too Many Requests — и первая реакция у многих: «модель никуда не годится, срочно меняем». Обычно с таким выводом спешить не стоит. Код 429 говорит лишь о том, что «кто-то тебя ограничил», но не отвечает ни на вопрос «кто», ни на вопрос «по какому параметру». Главная мысль статьи: сначала определи источник ограничения, а уже потом решай — ждать или переключаться.
Это не очередная общая статья про ретраи. Мы пройдём в реальном порядке диагностики: разберём текст ошибки, заголовки ответа и измерения лимитов, а затем дадим рекомендации по параметрам backoff и настройке цепочки переключения при сбоях (failover).
Главная ценность: после прочтения вы за пару минут сможете определить, откуда пришёл 429 — от upstream-провайдера, от промежуточного шлюза или из-за квоты бесплатного тарифа, — и настроить для своего приложения отказоустойчивую стратегию «где надо — подождать, где надо — переключиться».
Ключевые моменты при диагностике 429
429 — это стандартный HTTP-статус «слишком много запросов». В контексте API больших языковых моделей его может вернуть любой уровень цепочки вызовов. В таблице ниже собраны три самых частых источника и правильный способ реагировать на каждый из них.
| Источник ограничения | Типичные признаки | Нужно ли менять модель | Что делать |
|---|---|---|---|
| Провайдер модели (апстрим) | В теле ошибки — собственный тип ошибки и формулировка провайдера, в заголовках ответа — его поля ограничения частоты | Обычно нет | Отступить по Retry-After, при необходимости снизить параллелизм или запросить повышение квоты |
| Промежуточный шлюз / агрегатор | Формулировка ошибки от шлюза, сообщение о лимите на уровне аккаунта или группы | Нет | Проверить квоты и настройки параллелизма на стороне шлюза либо переключить группу шлюза |
| Бесплатный тариф / пробная квота | Сообщение о бесплатной квоте, дневном лимите запросов или нехватке ёмкости | Зависит от ситуации | Перейти на платный тариф или выбрать аналогичную модель с доступной ёмкостью |
Почему 429 не означает, что модель «легла»
Когда модель действительно недоступна, чаще приходят ошибки серии 5xx. Например, перегрузка у Anthropic возвращает 529 overloaded_error, а сбои шлюза или балансировщика обычно дают 502 и 503. Эти коды говорят о том, что сервер временно не справляется с нагрузкой, — и это совсем не то же самое, что «ваш аккаунт превысил квоту».
У 429 есть чёткая адресность: правило ограничения применяется именно к вам — к вашему API-ключу, вашей организации, вашему бесплатному тарифу или к скорости, которую вам выделил шлюз. Иногда сменой модели действительно можно обойти ограничение, но если лимит задан на уровне аккаунта в шлюзе, смена модели ничего не изменит — вы упрётесь в ту же стену. Если же лимит — это верхняя граница токенов в минуту у провайдера, достаточно подождать несколько секунд, и всё восстановится; а смена модели вдобавок внесёт неопределённость в качество вывода.
Разборы проблем Claude Code от третьих лиц это подтверждают: при 429 Claude Code показывает Request rejected (429), а следом — дословный текст от сервера. Именно этот текст и подсказывает, откуда пришло ограничение: от Anthropic, от шлюза или от бесплатного тарифа. Поэтому первый шаг в диагностике всегда один и тот же — прочитать полное сообщение об ошибке, а не смотреть только на статус-код.
Чем 429 отличается от смежных кодов состояния
Чтобы не путать разные ошибки, в таблице ниже перечислены коды состояния, которые при вызовах больших языковых моделей легко спутать с 429.
| Код состояния | Значение | Ответственная сторона | Подходит ли для повтора | Подходит ли для переключения при сбое |
|---|---|---|---|---|
| 429 | Слишком много запросов, сработало ограничение скорости или квоты | Квота вызывающей стороны | Да, нужен backoff | Переключаться, если backoff не помог |
| 529 | Перегрузка upstream-сервиса (особенность Anthropic) | Ёмкость серверной стороны | Да, короткий backoff | Да |
| 503 | Сервис временно недоступен | Сервер или шлюз | Да | Да |
| 500/502 | Внутренняя ошибка или ошибка шлюза | Сервер или шлюз | Ограниченное число повторов | Да |
| 400/401/403 | Проблемы с параметрами, аутентификацией или правами | Конфигурация вызывающей стороны | Нет | Нет, нужно исправить конфигурацию |
В этой таблице есть деталь, которую легко упустить: по данным сторонних тестов, механизм fallbackModel в Claude Code срабатывает только при перегрузке 529 и пробует максимум 3 запасные модели, а не при 429. Это показывает, что сами создатели инструмента считают: первая реакция на 429 — это backoff, а не смена модели.
Как определить, от кого пришёл 429: 3 шага диагностики
Ниже — схема разбора 429, которую можно повторять как есть. Шаги идут по возрастанию затрат, и в большинстве случаев всё решается уже на первом.
Шаг 1: Читаем тело ошибки 429 целиком
Не ограничивайтесь записью кода состояния в лог — сохраняйте тело ответа как есть. 429 от разных уровней заметно различаются формулировками, и это самая прямая подсказка.
- Ответ от провайдера-апстрима: в теле ошибки обычно есть поле с типом ошибки провайдера. Например, Anthropic отдаёт тип
rate_limit_error, а интерфейсы в стиле OpenAI — код вродеrate_limit_exceededи пояснение, превышен лимит по числу запросов или по токенам. - Ответ от шлюза: формулировки обычно оперируют собственными понятиями шлюза — «аккаунт», «группа», «токен», «канал» — либо прямо называют имя шлюза.
- Ответ бесплатного тарифа: встречаются слова вроде «free tier», «quota», «daily limit», «capacity». В сторонних тестах бесплатного доступа к некоторым моделям такие ёмкостные 429 попадаются особенно часто.
Если вы вызываете модель через сервис-прокси или агрегатор, обратите особое внимание на то, пробрасывает ли шлюз исходную ошибку апстрима как есть. Проброс означает, что ограничивает вас апстрим; собственные формулировки без проброса — что ограничивает шлюз.
Шаг 2: проверьте заголовки ответа 429
Заголовки ответа — вторая цепочка доказательств. Крупные провайдеры обычно возвращают в заголовках остаток квоты и время сброса, а шлюз может добавлять свои поля.
| Заголовок ответа | Типичный источник | Значение | Для чего использовать при диагностике |
|---|---|---|---|
Retry-After |
стандарт HTTP, используется многими | сколько секунд рекомендуется подождать | в первую очередь учитывать при backoff |
x-ratelimit-remaining-requests |
интерфейсы в стиле OpenAI | сколько запросов осталось в текущем окне | понять, не упираемся ли мы в лимит RPM |
x-ratelimit-remaining-tokens |
интерфейсы в стиле OpenAI | сколько токенов осталось в текущем окне | понять, не связан ли лимит с TPM |
anthropic-ratelimit-requests-remaining |
Anthropic | сколько запросов осталось | подтвердить, что ограничение идёт от Anthropic |
anthropic-ratelimit-input-tokens-remaining |
Anthropic | сколько входных токенов осталось | понять, не лимит ли это на входные токены |
Правило простое: если есть заголовок лимита с префиксом провайдера и остаток равен 0, почти наверняка вас ограничивает вышестоящий провайдер. Если же заголовков лимитов провайдера нет — есть только собственные поля шлюза или вообще ничего, — вероятность проблемы на уровне шлюза выше. Учтите: некоторые провайдеры в последние годы показывают точные лимиты только в консоли, поэтому информация в заголовках ответа может быть неполной. В таком случае возвращайтесь к формулировке ошибки из шага 1 и сравнению измерений из шага 3.
Шаг 3. Определяем измерение лимита
Когда вы поняли, кто именно вас ограничивает, стоит выяснить, что именно ограничивают. Правила ограничения скорости у разных провайдеров неодинаковы. Сторонний сравнительный обзор пяти провайдеров показывает: Anthropic в основном ограничивает число токенов в минуту, причём токены, попавшие в кэш, в лимит не засчитываются; DeepSeek в первую очередь ограничивает число одновременных запросов; а конкретные квоты OpenAI и Google чаще приходится смотреть в консоли.
Это напрямую влияет на стратегию настройки. Типичные соответствия такие:
- Превышен RPM (число запросов в минуту): объедините несколько небольших запросов в пакетные или добавьте на клиенте token bucket, чтобы отправлять их равномерно.
- Превышен TPM (число токенов в минуту): сократите контекст, включите кэширование промптов, а задачи с длинными документами разнесите по разным временным окнам.
- Превышено число одновременных запросов: уменьшите количество worker’ов и управляйте числом запросов «в полёте» с помощью очереди; один только backoff тут мало поможет.
- Исчерпана дневная квота или бесплатный лимит: backoff не имеет смысла — остаётся только дождаться сброса, перейти на более высокий тариф или переключиться на другой канал.
Четвёртый случай — единственный тип 429, при котором «backoff гарантированно бесполезен». Именно его нужно как можно раньше распознать и сразу переходить на резервный вариант (failover).
Как настроить стратегию повторов при 429
Убедившись, что 429 — это восстановимое ограничение скорости, переходим к этапу backoff. Цель backoff — не «повторить как можно быстрее», а «как можно быстрее восстановиться, не усугубляя перегрузку».
Экспоненциальный backoff с джиттером
Самый распространённый вариант — экспоненциальный backoff (Exponential Backoff) с джиттером (Jitter). Время ожидания при n-й попытке примерно равно «базовая задержка × 2 в степени n», плюс случайная добавка, и всё это с верхним ограничением. Джиттер нужен, чтобы разнести моменты повторов у разных клиентов и не дать им ударить в одну и ту же секунду, устроив «шторм повторов».
Если в ответе есть Retry-After, его приоритет должен быть выше рассчитанного вами времени backoff. Сервер лучше знает, когда сбросится окно, — ждать по его подсказке обычно и есть самый быстрый путь к восстановлению.
Рекомендуемые значения параметров backoff
В таблице ниже — стартовый набор параметров, подходящий для большинства диалоговых и пакетных сценариев; на практике их можно подстроить под допустимую задержку в вашем продукте.
| Параметр | Рекомендуемое стартовое значение | Описание |
|---|---|---|
| Базовая задержка | 1 секунда | Время ожидания перед первой попыткой |
| Множитель backoff | 2 | Время ожидания удваивается с каждой попыткой |
| Максимальное одиночное ожидание | 30–60 секунд | Чтобы время ожидания не росло бесконечно |
| Максимальное число повторов | 3–5 | После этого — переключение или ошибка |
| Джиттер | 0–100% от времени ожидания, случайно | Рекомендуется «полный джиттер», чтобы разнести повторы |
| Retry-After | Приоритет, если есть | Перекрывает самостоятельно рассчитанное время backoff |
Два нюанса настройки часто упускают. Первый: в интерактивных сценариях (например, в чат-интерфейсе) общее время ожидания не должно быть слишком большим — стоит задать общий бюджет таймаута, после которого сразу переключаемся или показываем пользователю сообщение. Второй: не нужно делать backoff-повторы для ошибок конфигурации вроде 400, 401, 403 — сколько ни жди, сами они не исправятся, только зря потратите время и квоту.
Если вы используете официальный SDK, многие SDK уже имеют встроенные автоматические повторы для 429 и 5xx, обычно они управляются параметром вроде max_retries. Прежде чем оборачивать всё в собственный слой повторов, проверьте поведение SDK по умолчанию — иначе два уровня ретраев перемножат реальное число попыток.
Как настроить failover при 429
Backoff — это «подождать на месте», а failover — «пойти другой дорогой». Это не выбор одного из двух, а последовательность: сначала backoff, если он не помог — переключение.
Когда запускать failover
Переключаться стоит при любом из условий ниже, а не при первом же 429:
- достигнут лимит повторных попыток, а 429 всё равно продолжает приходить;
- текст ошибки прямо указывает на исчерпание суточной квоты, бесплатного лимита или на «нехватку мощностей»;
- время ожидания из
Retry-Afterпревышает допустимый для бизнеса предел; - один и тот же канал за короткое время несколько раз подряд падает и достигает порога срабатывания предохранителя.
Рекомендации сторонних специалистов по обработке частых 429 для одной популярной модели на OpenRouter идут по той же логике: сначала backoff, затем failover на другую модель в рамках того же интерфейса. Такой порядок позволяет сохранить качество вывода исходной модели и не допустить простоя сервиса.
Три варианта цепочки failover
У «запасных маршрутов» failover есть разные уровни; стоимость переключения растёт в таком порядке:
- Та же модель, другой канал: та же модель, но другой API-ключ, другая группа или другой провайдер. Лучшая согласованность вывода — поэтому это первый выбор.
- Тот же вендор, другой уровень: например, переход с флагманской модели на лёгкую модель той же линейки. Возможности немного ниже, но стиль близкий.
- Другой вендор, другая модель: переход на модель того же класса у другого поставщика. Доступность максимальная, но работу с промптами и формат вывода нужно проверить заранее.
Поверх этого стоит добавить ещё один слой — предохранитель (circuit breaker): когда число последовательных сбоев на канале достигает порога, на время охлаждения этот канал просто пропускается; после охлаждения отправляем несколько пробных запросов, а когда канал восстановился, постепенно возвращаем нагрузку. Это избавляет от ситуации, когда каждый запрос сначала упирается в стену, а потом переключается, и заметно снижает общую задержку.
Обе стратегии, показанные на схеме выше, можно проверить в реальном проекте через один и тот же унифицированный интерфейс. На платформах вроде APIYI (apiyi.com), совместимых с форматами интерфейсов OpenAI и Anthropic, один и тот же код: достаточно изменить параметр model, чтобы переключиться на резервную модель. Это гораздо проще, чем поддерживать отдельный SDK для каждого вендора.
Быстрый старт: обработка 429 при ограничении частоты запросов
Ниже — всё из предыдущих разделов, собранное в один чек-лист конфигурации, по которому можно сверяться и сразу внедрять. Кода в тексте нет — используйте его как проверочный список при код-ревью или настройке эксплуатации.
Чек-лист из 5 пунктов конфигурации
- Логирование: записывайте полное тело и заголовки ответа — как минимум код статуса, тип ошибки, текст ошибки,
Retry-Afterи всевозможные поляratelimit. - Классификация: на стороне клиента делите ошибки на три категории — «можно отступить» (429 скоростные, 529, 503), «нужно переключиться» (исчерпана квота, постоянные сбои), «повторять бессмысленно» (400, 401, 403).
- Отступление: настройте экспоненциальный backoff с полным джиттером по параметрам из таблицы выше, с приоритетом
Retry-After, а также задайте максимальное число попыток и общий бюджет таймаута. - Цепочка переключений: выстройте резервный список в порядке «тот же модель → другой канал → та же компания → другой тариф → другая компания → другая модель» и заранее проверьте, как промпт работает на каждой резервной модели.
- Предохранитель и алерты: для каждого канала задайте порог сбоев и время остывания, а также настройте алерт на долю 429 — если она стабильно высокая, значит пора запрашивать увеличение лимита или снижать параллелизм.
Пример цепочки резервных моделей
В таблице ниже — схема типичной трёхуровневой цепочки переключений. Конкретные названия моделей смотрите в списке моделей платформы, тарифы — на странице цен; конкретные цены за единицу в этой статье не приводятся.
| Уровень | Логика выбора | Формат интерфейса | Доступные платформы | Основа цены |
|---|---|---|---|---|
| Основная | Флагманская модель с лучшим качеством для задачи | Формат OpenAI или Anthropic | APIYI apiyi.com, официальный API | Согласно docs.apiyi.com/models |
| Резерв первого уровня | Другой канал или группа той же модели | Такой же, как у основной | APIYI apiyi.com, официальный API | Согласно docs.apiyi.com/models |
| Резерв второго уровня | Облегчённая модель той же компании или аналогичная модель другой компании | Формат, совместимый с OpenAI | APIYI apiyi.com и другие агрегаторы | Согласно docs.apiyi.com/models |
Что касается подключения: если вы используете официальные SDK OpenAI или Anthropic, обычно достаточно заменить base_url на адрес, который предоставляет платформа, а api_key — на ключ платформы. Конкретные адреса интерфейсов и инструкции по вызову каждой модели лучше сверять с центром документации APIYI docs.apiyi.com, а не копировать непроверенные адреса из интернета.
🚀 Быстрый старт: при построении отказоустойчивой цепочки под 429 рекомендую сначала через APIYI apiyi.com подключить основную и резервные модели одним и тем же кодом. Платформа предоставляет вызовы API всех основных моделей из этой статьи, совместима с форматами интерфейсов OpenAI и Anthropic — для смены модели достаточно поменять параметр
model. Документация по подключению — на docs.apiyi.com, а цены за вход и выход по каждой модели, стоимость кеширования и правила тарификации смотрите в актуальных данных на странице цен docs.apiyi.com/models.
Частые вопросы (FAQ)
Вопрос 1: Что такое ограничение скорости 429?
429 — это стандартный HTTP-код состояния Too Many Requests. Он означает, что вызывающая сторона в определённом временном окне превысила допустимое число запросов, токенов, параллельных соединений или общую квоту. Он говорит о том, что «вас ограничили», а не о том, что сама модель вышла из строя.
Вопрос 2: Чем 429 отличается от 529 и 503?
429 указывает на проблему с квотой на стороне вызывающей стороны — ответственность на «вы слишком много используете»; 529 — это ошибка перегрузки у Anthropic, 503 — сервис временно недоступен, и в обоих случаях ответственность лежит на ёмкости серверной стороны. В первом случае приоритет — отступить (backoff) и скорректировать объём использования, во втором и третьем лучше после короткого backoff сразу переключаться на резервный вариант (failover).
Вопрос 3: Как быстрее всего определить, откуда пришёл 429 — от поставщика модели или от шлюза?
Сначала смотрите на формулировку тела ошибки: если в ней есть тип ошибки поставщика, скорее всего, она пришла от поставщика; если упоминаются аккаунт, группа, канал и т.п. — обычно это шлюз. Затем посмотрите на заголовки ответа: если присутствует поле `ratelimit` с префиксом поставщика и остаток равен 0, можно практически с уверенностью утверждать, что ограничивает поставщик.
Вопрос 4: Почему после множества повторных попыток с backoff 429 так и не проходит?
Самая частая причина — неверно определён аспект, по которому происходит ограничение. Если исчерпана суточная квота или бесплатный лимит, backoff заведомо бесполезен; если превышено число параллельных соединений, а клиент продолжает отправлять запросы с высокой параллельностью, backoff тоже лишь немного смягчит ситуацию. В этом случае нужно снизить параллельность или сразу перейти к failover.
Вопрос 5: Как быстро построить цепочку переключения между несколькими моделями?
Рекомендуется проверять на платформе с единым интерфейсом для нескольких моделей:
1. Зарегистрируйте аккаунт на APIYI apiyi.com и получите API Key;
2. Настройте `base_url` по документации docs.apiyi.com, подключайтесь в формате OpenAI или Anthropic;
3. Настройте в клиенте список основной и резервной моделей, а переключение выполняйте, меняя параметр `model`.
Так основная и резервная модели используют один и тот же код, и стоимость тестирования цепочки переключения будет намного ниже.
Вопрос 6: Не приведёт ли failover к неконтролируемым расходам?
Такое возможно. Цена за единицу, длина контекстного окна и стратегия кэширования у резервной модели могут отличаться от основной, а частые переключения изменят структуру счёта. Рекомендуется заранее сверять цены по каждой резервной модели, ориентируясь на фактические данные со страницы цен APIYI docs.apiyi.com/models, и настроить оповещения о доле переключений.
Вопрос 7: Какие известные ограничения есть у подходов к обработке 429?
Backoff увеличивает задержку запросов и не подходит для сценариев с очень высокими требованиями к реальному времени; переключение между разными поставщиками может привести к различиям в стиле и формате вывода, поэтому требуется заранее провести регрессионное тестирование; некоторые поставщики показывают лимиты только в консоли, а информация в заголовках ответа неполная, поэтому при диагностике приходится полагаться лишь на формулировку ошибки и данные мониторинга.
Ключевые выводы: обработка 429 (ограничение частоты запросов)
- 429 говорит только о том, что вас ограничили: он не сообщает, кто именно ограничил и что именно ограничено, поэтому его нельзя напрямую приравнивать к сбою модели.
- Сначала прочитайте текст ошибки: формулировка в теле ошибки — самый быстрый способ понять, дело в upstream, шлюзе или бесплатном тарифе.
- Затем посмотрите на заголовки ответа: поля
ratelimitс префиксом вендора иRetry-After— вторая цепочка доказательств. - Устраняйте причину по измерению: RPM — выравнивайте равномерно, TPM — сокращайте контекст, конкурентность — ограничивайте число воркеров, исчерпание квоты — сразу переключайтесь.
- Сначала backoff, потом переключение: экспоненциальная задержка с полным джиттером, приоритет у
Retry-After, у повторов есть предел. - Каскад переключений проектируйте послойно: сначала смена канала для той же модели, затем смена модели у другого провайдера как запасной вариант, в связке с предохранителем (circuit breaker).
- Снижайте затраты через единый интерфейс: через APIYI, совместимый с форматами OpenAI и Anthropic, одним набором кода можно управлять основной и резервной моделями.
Итог
При 429 правильный порядок — «определить источник → понять измерение → backoff → переключение», а не сразу менять модель:
- Определить источник: формулировка тела ошибки плюс заголовки ответа, чтобы различить upstream-провайдера, шлюз и бесплатный тариф.
- Определить измерение: понять, это число запросов, количество токенов, конкурентность или общая квота — от этого зависит, поможет ли backoff.
- Настроить отказоустойчивость: экспоненциальный backoff с джиттером как первая линия обороны, послойное переключение при сбоях плюс circuit breaker как вторая.
Если закрепить этот процесс в логах, классификации ошибок и конфигурации клиента, 429 превращается из «ночного алерта» в предсказуемое, самовосстанавливающееся рутинное событие.
Рекомендуем быстро проверить переключение основной и резервной моделей через APIYI apiyi.com; инструкция по подключению — в docs.apiyi.com, а цены на модели и правила тарификации — в docs.apiyi.com/models.
📚 Справочные материалы
- Rate Limit Reached in Claude Code: What Each 429 Message Means: что означает каждое сообщение об ошибке 429 в Claude Code
- Ссылка:
ofox.ai/blog -
Описание: как по дословной формулировке на стороне сервера отличить ограничения Anthropic, шлюза и бесплатного тарифа
-
Claude Code fallbackModel: 3-Tier Failover Setup: настройка резервной модели в Claude Code
- Ссылка:
ofox.ai/blog -
Описание: показывает, что fallbackModel срабатывает при перегрузке 529 и поддерживает максимум 3 модели, но не при 429
-
LLM API Rate Limits Compared: сравнение правил ограничения запросов у 5 крупных провайдеров больших моделей
- Ссылка:
ofox.ai/blog -
Описание: сравнение разных подходов к лимитам — по токенам, по конкурентности и тех, что показываются только в консоли
-
Центр документации и страница цен APIYI: инструкция по подключению и тарификация моделей
- Ссылка:
docs.apiyi.comиdocs.apiyi.com/models - Описание: формат интерфейса, настройка base_url и фактические цены моделей — ориентируйтесь на эти данные
Автор: техническая команда APIYI
Обсуждение: будем рады пообщаться на главной странице APIYI apiyi.com — расскажем о практиках работы с лимитами и отказоустойчивостью; больше материалов по подключению ищите в центре документации docs.apiyi.com
