Ошибка 429 у ИИ-агента: ожидание, пределы и полезный отказ

Провайдер ограничил запрос, агент решил немедленно повторить. Затем ещё раз. Посетитель смотрит на анимацию, очередь растёт. Разбираем, как превратить 429 в управляемое состояние вместо усилителя нагрузки.

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

Агент получил 429 и решил стараться ещё сильнее

Учебная ситуация: помощник готовит ответ посетителю и обращается к API модели. Провайдер ограничил поток. Система немедленно повторяет запрос, затем повторяет его ещё несколько раз. Пользователь смотрит на анимацию, очередь растёт, другие задачи тоже начинают задерживаться. Из локального ограничения получился небольшой усилитель нагрузки.

Ошибка 429 не требует от агента большей настойчивости. Она требует понять причину ограничения и выбрать управляемое продолжение. Иногда нужно подождать. Иногда — снизить поток. Иногда доступ не восстановится без изменения квоты или решения владельца. А если срок полезности задания уже истёк, правильным исходом станет остановка, даже когда технически можно попробовать ещё раз.

Разберём один контур: запрос ИИ-агента упёрся в лимит API. Что сохранить, сколько ждать, где прекратить повтор и как не размножить последующие действия? Это не обзор всех инцидентов сопровождения и не инструкция бесконечно увеличивать бюджет. Нужен небольшой рабочий контракт отказа, который понятен инженеру и владельцу бизнес-задачи.

Код один, обстоятельства разные

Сначала сохраняются код, тип ошибки, полезные заголовки и время. Сообщение может указывать на ограничение частоты, объёма токенов, доступного ресурса или другой предел провайдера. Нельзя выводить причину только по слову «лимит». Для решения важны конкретный API, учётная область и актуальное описание ошибки.

RFC 6585 описывает 429 как ограничение числа запросов и допускает указание ожидания. Сам статус не задаёт универсальную политику восстановления бизнес-задачи.

У поставщика могут существовать разные пределы одновременно. Маленькое число больших запросов способно упереться не в частоту вызовов, а в объём обработки. Быстрый повтор того же большого задания не изменит условия. Поэтому полезно наблюдать размер и характер работы, а не только счётчик HTTP-запросов.

Документация Anthropic о лимитах API различает ограничения и поведение заголовков. В частности, не всякий описанный 429 предполагает обычное краткое ожидание. Особенности конкретного поставщика проверяются отдельно.

Если причина неизвестна, это должно быть видно в состоянии. Можно временно остановить поток и передать диагностику ответственному. Лучше назвать ограничение неразобранным, чем выдавать случайный таймер за осмысленное восстановление. Автоматизация не обязана решать все классы отказов одинаковым повтором.

Срок задания важнее желания получить успешный ответ

У вопроса посетителя есть время полезности. Ответ, приготовленный после ухода человека, может ещё пригодиться сохранённой задаче, а может стать бесполезной нагрузкой. У внутреннего отчёта другой горизонт. Поэтому у задания нужен срок или условие актуальности, которое проверяется перед ожиданием и перед новым исполнением.

В учебном примере посетитель запросил короткое уточнение перед выбором. Если API недоступен дольше предусмотренного ожидания, интерфейс предлагает понятный выход: сохранить вопрос, передать специалисту или вернуться позже. Не следует держать человека перед бесконечным «ещё немного думаем». Техническая очередь продолжает существовать, но пользовательское обещание уже нарушено.

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

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

Как читать Retry-After

Заголовок ожидания нужно разобрать по формату, а не воспринимать как произвольную строку. MDN описывает Retry-After в виде числа секунд или HTTP-даты. Это помогает выбрать допустимое время следующей попытки.

После разбора время сравнивается со сроком задания. Если ждать можно дольше, чем осталось до потери полезности, повтор не планируется автоматически. Возникает другой исход: задача не завершена в доступном горизонте. Для человека это может означать предложение альтернативы, для внутреннего процесса — очередь ручного решения. Успех API через час не исправляет пропущенное обещание ответить сейчас.

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

Дата требует корректного времени и учёта задержки. Если часы исполнителя сильно отличаются, рассчитанное ожидание станет неверным. Для диагностики полезно сохранять исходное значение и выбранный момент, а не только финальный таймер. Тогда можно объяснить, почему система повторила слишком рано или оставила задачу ждать дольше, чем ожидалось.

Ограниченный повтор вместо ускоряющейся очереди

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

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

Повторять не всегда нужно тот же большой запрос в прежнем виде. Иногда помогает уменьшить объём или разделить задачу, если это сохраняет смысл. Но автоматическое сокращение контекста может ухудшить ответ. Поэтому изменение задания должно быть предусмотрено и проверено. Нельзя ради прохождения лимита выбросить важные условия, а результат выдать за полный разбор.

Параллельность тоже ограничивается. Если каждый ожидающий запрос живёт в собственной независимой петле, общий поток продолжает давить на один предел. Нужен согласованный регулятор нагрузки для соответствующего ресурса. Его область определяется устройством провайдера и проекта. Это вопрос пропускной способности, а не повод дать агенту право бесконтрольно менять учётные данные или обходить ограничения.

Три временные диаграммы

Первая учебная диаграмма: запрос получил ограничение, система установила допустимое ожидание, срок задачи ещё позволяет продолжение. После паузы выполняется ограниченный повтор и получается ответ. В истории видно, сколько времени заняли ожидание и обработка. Пользовательское состояние сообщает о задержке и затем о фактическом результате.

Вторая: ждать предложено дольше оставшегося горизонта. Система не ставит красивую галочку «повтор назначен», а завершает текущий автоматический путь. Человек получает альтернативу или задачу для сотрудника. Позднее восстановление доступности API не должно незаметно вернуть уже завершённый сценарий в работу без предусмотренной причины.

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

Эти три пути полезно нарисовать рядом. Они показывают, почему одна обработка «на любой 429 подождать и повторить» неполна. У каждого пути своё основание, финальное состояние и ответственный. Различие должно существовать в коде и журнале, а не только в презентации о надёжности.

Что увидит человек, пока система ждёт

До настройки полезно выяснить, на каком уровне уже выполняются повторы. Их может делать библиотека подключения, внешний обработчик и сам планировщик. Если каждый слой независимо считает свои попытки, фактическое число запросов оказывается больше видимого лимита одного слоя. Это условный архитектурный риск, а не утверждение о поведении любой конкретной библиотеки.

Для проверки достаточно искусственно вернуть ограничение и посчитать реальные исходящие обращения. Затем сравнить их с журналом бизнес-задачи. Владелец должен видеть полный расход, а не только число повторов внешнего обработчика. Политике нужен один согласованный предел и понимание того, какие вложенные действия в него входят. Иначе ограниченная снаружи схема остаётся настойчивой внутри.

Индикатор процесса должен соответствовать реальности. Если модель ещё не начала обработку из-за ограничения, не стоит показывать выдуманные этапы анализа. Достаточно сообщить о задержке и доступном продолжении. Промежуточные сообщения полезны, когда объясняют выполненную работу, а не маскируют техническое ожидание под интеллектуальную деятельность.

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

Если запрос отменён пользователем, очередь должна учитывать отмену. Нет смысла продолжать дорогое исполнение и затем объявлять его готовым для уже закрытой задачи. Техническая отмена может иметь ограничения, которые нужно знать. Но даже если остановить текущий вызов нельзя, последующее действие и статус результата всё равно контролируются приложением.

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

Генерация ответа и внешнее действие имеют разные последствия

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

Если подтверждение внешней операции потерялось, сначала устанавливается её состояние доступным способом. Неопределённый ответ нельзя считать доказательством отсутствия действия. Подробная защита от повторных событий разобрана в статье о вебхуках и дублях. Здесь важно удержать границу: восстановление доступа к модели не разрешает заново выполнять уже состоявшийся бизнес-шаг.

В черновике задачи можно хранить, какой этап завершён и какой ждёт. Например, источники уже проверены, текст ещё не подготовлен, отправки не было. Это позволяет продолжить с нужного места и объяснить состояние сотруднику. Общая строка «ошибка агента» теряет эту информацию и провоцирует полный повтор.

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

Паспорт отказа для сопровождения

Ниже — заготовка, которую можно заполнить для одного провайдера и одного типа задачи. Она помогает договориться о поведении до инцидента. Это не универсальные значения таймеров, а состав проверяемой политики.

Данные журнала должны помогать диагностике, но не копировать без необходимости всё содержание запросов. Для многих случаев достаточно идентификатора, размеров, версии и безопасного описания операции. Состав определяется проектом. Отчёт о лимите не должен становиться дополнительным хранилищем чувствительных материалов компании.

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

Как принять обработку лимита до рабочего инцидента

Подготовьте управляемые тестовые ответы: временный 429 с корректным ожиданием, заголовок-дата, отсутствующий заголовок, причина, не исправляемая короткой паузой, и успешный ответ после ограниченного повтора. Для каждого примера заранее определите допустимый исход. Не нужно реально перегружать платный сервис, чтобы проверить ветвление собственного кода.

Добавьте тест истечения срока во время ожидания. Затем отмену пользователя и изменение исходных данных. Проверьте, что дальнейшее действие не выполняется по устаревшему состоянию. Такие случаи часто важнее позитивной демонстрации «со второго раза получилось». Они показывают, умеет ли процесс корректно отказаться от уже ненужной работы.

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

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

Добавьте некорректное значение ожидания: неизвестный формат, отрицательное число или дату, которую приложение не смогло разобрать. Исполнитель не должен назначать отрицательную паузу либо мгновенно входить в новый цикл. Ожидается предусмотренное ограниченное правило или передача ошибки. В журнале сохраняют исходный заголовок и причину отказа от его использования, чтобы поддержку не заставляли воспроизводить дефект по случайной задержке.

Стоимость надёжности видна в очереди

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

Общий расход токенов разобран в материале о бюджете ИИ-агента. Здесь экономика связана с отказом: сколько стоит незавершённость и какие повторы действительно нужны. Дешёвый отдельный запрос не оправдывает бесконечную обработку задачи, которая потеряла смысл.

При сопровождении ИИ-агентов полезно согласовать паспорт такого отказа как часть рабочего контура. Это конкретнее обещания «мониторим всё». Известны причины, допустимое ожидание, пределы и владелец исключения. Совместимость и особенности каждого API проверяются отдельно; универсальный обработчик не должен скрывать различие поставщиков.

Хорошая обработка 429 не делает вид, что ограничения исчезли. Она сохраняет задачу в пределах её смысла, защищает последующие действия и умеет остановиться с объяснением. Агенту не нужно доказывать настойчивость количеством попыток. Нужно либо завершить полезную работу, либо вовремя передать человеку понятное незавершённое состояние.