OpenRouter 429 означает ограничение частоты запросов или токенов: приложение сохраняет ответ, проверяет доступные метаданные и заголовок Retry-After, затем решает вопрос об ограниченном повторе. При этом повтор обращения к модели и повтор действия в бизнес-процессе должны жить в разных контурах. Так приложение удерживает временный сбой генерации внутри очереди и сохраняет однократность отправки сообщения, создания записи или списания.
Значение ответа
По документации OpenRouter код HTTP 429 означает ограничение частоты; `error_type` со значением `rate_limit_exceeded` уточняет категорию ошибки провайдера. Заголовок `Retry-After` может присутствовать, поэтому приложение проверяет его наличие в каждом ответе.
Первый шаг диагностики — сохранить факты запроса и ответа без секретов: внутренний идентификатор операции, выбранный маршрут модели, статус HTTP, текст ошибки, безопасные поля метаданных и факт начала выдачи результата. В официальном описании ошибок OpenRouter ответ до начала генерации показан как объект `error` с кодом, сообщением и возможными метаданными. Эти поля полезнее догадки по одному числу статуса. Для пользовательского интерфейса заранее определите короткие состояния: запрос ожидает повтор, требует разбора или завершён. Каждое состояние должно соответствовать записи в журнале.
Если модель уже начала выдавать ответ, статус соединения может остаться успешным, а ошибка придёт внутри тела или события потока. Документация прямо описывает такую ситуацию. Поэтому обработчик проверяет завершение потока и структуру результата, даже когда заголовки HTTP выглядят обычными. Частично полученный текст помечайте как черновик: он способен обрывать условие, цитату или список действий. Сотруднику показывайте понятный статус задачи и причину ожидания, сохраняя сырые технические детали в журнале.
Эта статья посвящена именно коду 429 и маршруту повтора. Общая схема работы с API и маршрутизацией модели решает другой вопрос: как направить обычный запрос к выбранному провайдеру. Здесь важны точка возникновения ограничения, безопасное ожидание и сохранение состояния уже начатой операции.
Источник ограничения
Код 429 сам по себе сообщает категорию проблемы, но происхождение ограничения требует дополнительных признаков. В официальной документации для ошибок провайдера указано поле `error_type`; когда доступен исходный код провайдера, он содержится в `error.metadata.provider_code`. Дополнительный контекст маршрута может присутствовать в `openrouter_metadata` при соответствующей настройке запроса. Отсутствующее поле оставляйте как неизвестное, сохраняя исходный ответ для разбора.
| Сигнал | Как читать | Следующий шаг |
|---|---|---|
| HTTP 429 до вывода | Запрос ограничен до готового ответа | Проверить заголовок и метаданные |
| `rate_limit_exceeded` | Категория ограничения запросов или токенов | Сверить маршрут и допустимость повтора |
| Код провайдера | Дополнительный признак при наличии | Сохранить вместе с ошибкой |
| Ошибка внутри потока | Вывод мог оборваться при успешном HTTP-статусе | Отметить частичный текст и остановить действие |
Соседние ошибки требуют иного решения. В описании OpenRouter недостаток доступного баланса относится к коду 402, а блокировка правилами или правами — к 403. Такое различие защищает очередь от бесполезного повторения запросов. Технический журнал хранит категорию, исходное сообщение и идентификатор операции; человек видит короткую причину и владелец интеграции получает материал для проверки. Если организация использует несколько маршрутов, запись о выбранном маршруте помогает локализовать проблему без голословного вывода о виновной стороне. При передаче инцидента инженеру приложите очищенный пример тела ошибки и отметку о наличии заголовка ожидания. Это сокращает число предположений при разборе.
В материале о пилоте внутреннего сервиса через API раскрыта общая организация запросов. Здесь к ней добавляется диагностика результата на границе приложения: статус, метаданные и признаки частичной выдачи.
Правило повтора
После установления категории ошибки проверьте `Retry-After`. Документация OpenRouter говорит, что этот стандартный заголовок может сопровождать ответ 429 и задаёт паузу перед повтором. Значение нужно разобрать как заголовок ответа, проверить корректность и применить в пределах политики приложения. Если заголовка нет, используйте заранее согласованный алгоритм ожидания с верхней границей попыток и общей границей ожидания. Выбор собственной задержки команда согласует с нагрузкой и поведением клиента.
- Получите статус и завершите чтение тела или потока до классификации результата.
- Запишите `error_type`, доступные метаданные и наличие `Retry-After`.
- Проверьте, допускает ли операция безопасный повтор и остаётся ли задача актуальной.
- Поставьте повтор в очередь с ограничением попыток и учётом уже выполненных попыток библиотеки.
- После ответа обновите состояние одной исходной операции и передайте результат человеку.
Некоторые клиентские библиотеки уже учитывают `Retry-After` для статусов, которые повторяют автоматически; это отмечено в официальном руководстве OpenRouter. Проверьте поведение выбранной библиотеки перед добавлением собственного цикла. Если оба уровня повторяют запрос независимо, приложению сложнее понимать фактическое число обращений и состояние задачи. Повтор должен проходить через одну точку учёта, где видны причина, очередность и окончательное решение. Владелец очереди должен видеть политику попыток в одном месте и менять её через проверяемую настройку. Разрозненные повторы в разных слоях приложения затрудняют диагностику.
Для потоковой выдачи отдельно определите судьбу частичного текста. Оборванный ответ хранится как диагностический артефакт, а новое обращение формирует новый кандидат ответа. Человек видит, какой вариант завершился корректно. Такой подход помогает избежать склейки несовместимых фрагментов при повторной генерации.
Защита действия
Самая опасная ошибка рабочего процесса возникает после генерации. Допустим, модель подготовила текст уведомления, а приложение уже отправило его клиенту. Повтор запроса из-за сетевой неопределённости может привести ко второму уведомлению, если отправка спрятана в той же функции. Разделите генерацию проекта и выполнение действия. Для каждой задачи создайте устойчивый внутренний идентификатор; сервер по нему проверяет, было ли действие завершено, и требует отдельного подтверждения для нового выполнения.
Тот же принцип относится к созданию карточки в CRM, изменению документа и запуску команды. Модель предлагает содержание и объясняет гипотезы, а сервер проверяет право пользователя, состояние задачи и уникальность операции. Повтор генерации обновляет проект ответа, но сохраняет историю прежнего варианта. Подтверждение привязывается к выбранному проекту, чтобы сотрудник видел точный текст перед действием. Разделение полезно и при коде 429, и при обрыве потока после частичной выдачи.
Предложите пилот на внутренней операции без внешней отправки. Создайте контрольные ответы с кодом 429, с заголовком ожидания и без него, а также ошибку внутри потока. Проверьте журнал, очередь повтора и однократное подтверждение действия владельцем процесса.
Если приложение уже связывает модель с CRM или документами, маршрут стоит рассматривать как часть внедрения ИИ в процессы. Состав работ зависит от числа интеграций, состояния очереди, правил доступа и требований к журналу. Напишите нам, посчитаем под вашу задачу после разбора текущего вызова и точки, где выполняется внешнее действие.
Хотите разобрать повтор без дублей в вашем приложении?
Проверка сценария
Проверяйте обработчик на управляемых ответах, где заранее известен ожидаемый переход состояния. Нужны ответ 429 с корректным `Retry-After`, ответ без заголовка, иной код ошибки, успешный результат и ошибка после начала потока. Для каждого случая задайте, какую запись получит журнал, когда допустим повтор и что увидит сотрудник. Особое внимание уделите случаю, где действие уже подтверждено: повторный запрос к модели оставляет исполненное действие в завершённом состоянии. Запустите один и тот же контрольный случай через обычный ответ и через поток: пути регистрации ошибки различаются, а состояние бизнес-операции должно совпасть.
Сверьте также отказ владельца от задачи во время ожидания. Очередь помечает операцию завершённой и исключает её из дальнейших попыток; сервер проверяет актуальный статус перед каждым вызовом. Если исходная задача изменилась, старый ответ сохраняется в истории, а сотруднику предлагают заново оценить новый проект. Тестирование переходов и отката подробнее раскрыто в статье о проверке ИИ-агентов.
После пилота утвердите ответственных за лимиты очереди, техническую диагностику и разрешение внешних действий. Сохраните примеры ошибок с очищенными метаданными и правила обработки каждого типа. Для финансовой оценки учитывайте повторные запросы как отдельную нагрузку без предположений о тарифе; общие статьи про скрытые расходы на ИИ помогают поставить этот вопрос в планирование. Успешный результат — понятная причина ожидания, ограниченное число повторов и единственное подтверждённое действие для одной операции. После изменения библиотеки или маршрута модели повторяйте контрольные случаи. Так команда заметит, если новый клиент начал самостоятельно повторять ответы и изменил фактический поток запросов.