Лимит API AI-агента: безопасные повторы

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

Сложность не в том, чтобы подождать несколько секунд. Важно сохранить смысл исходной задачи, когда первый запрос мог не дойти до provider, завершиться на его стороне или оказаться частью нескольких запусков агентов, исчерпавших одну общую квоту. Безопасная архитектура разделяет эти случаи и заранее определяет вмешательство человека как штатный результат, а не как неловкое исключение.

429 это указание для планировщика, а не ошибка, которую нужно забрасывать запросами

HTTP 429 означает, что server отклоняет запрос, потому что client отправил слишком много запросов за период, который контролирует server. RFC 6585 определяет этот код статуса и указывает, что тело ответа должно объяснять условие и может содержать заголовок Retry-After. Это важно: 429 не говорит агенту, что немедленный повтор того же запроса с большой вероятностью сработает.

Сначала агент должен сохранить provider, endpoint, идентификатор учётных данных или аккаунта, класс запроса, статус ответа и все заголовки ограничения частоты. Затем ему следует перевести работу в отложенное состояние. Не позволяйте языковой модели каждый раз описывать это решение в тексте после сбоя. Транспортному уровню нужна детерминированная логика, потому что модель под давлением задачи часто попробует соседний endpoint, изменит фильтр или создаст второй путь запроса. Такие импровизации могут умножить число вызовов, не меняя результат и получая тот же отказ.

Отказ часто относится к более широкой корзине, чем текущий запрос. Provider-ы обычно задают лимиты для аккаунта, проекта, токена, IP-адреса, семейства endpoint-ов или их сочетания. Один агент может получить 429, пока другой агент с теми же учётными данными ещё некоторое время продолжает работу. Это не доказывает, что первый агент может безопасно повторить запрос. Возможно, у provider-а несколько корзин или второй процесс расходует последние доступные ресурсы.

Ведите локальный реестр для каждой известной области действия. Если service документирует лимит на токен, группируйте запросы по токену. Если он даёт только рекомендации для аккаунта, считайте, что все workers этого аккаунта используют одну корзину, пока данные не покажут обратное. Локальный реестр не будет идеально отражать внутренний счётчик provider-а, но не даст вашим workers вслепую конкурировать друг с другом.

Спецификация IETF RateLimit Fields, RFC 9333, определяет RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. Эти поля описывают состояние квоты, но не отменяют уже полученный 429. Используйте их, чтобы регулировать будущие запросы и не заполнять очередь быстрее, чем provider может их принять. Определяйте область действия этих полей по документации provider-а: один заголовок может не показывать, относится ли он к одному endpoint или ко всему аккаунту.

Полезная запись состояния выглядит так:

{
  "provider": "billing-api",
  "scope": "account:ops-team",
  "request_class": "write:invoice",
  "next_allowed_at": "2025-04-08T14:12:31Z",
  "remaining": 0,
  "reset_after_seconds": 60,
  "source": "HTTP 429 Retry-After"
}

Перед отправкой очередного вызова runner агента должен прочитать эту запись. Для небольшой команды в командной строке допустимо ждать внутри одного обработчика запроса. Когда появляются несколько workers, инструментов или возобновлённых задач, лучше использовать очередь с видимым next_allowed_at. Планировщик сможет выбрать другую работу вместо того, чтобы удерживать занятый процесс, а оператор получит понятное объяснение задержки.

Бюджеты повторов не дают небольшому сбою превратиться в поток запросов

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

Используйте отдельные бюджеты для каждой задачи и каждой общей области provider-а. Бюджет задачи отвечает на вопрос: «Сколько неопределённости может выдержать эта цель?» Бюджет области отвечает на другой вопрос: «Какое нарушение работы вся текущая нагрузка может создать для provider-а?» Если десять задач получают по три повтора, аккаунт всё равно может получить тридцать дополнительных запросов. Так якобы осторожная политика превращается во всплеск.

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

Представьте правило как данные, которые агент не может легко переопределить:

request_classes:
  read:
    max_attempts: 4
    max_wait_seconds: 90
    retry_statuses: [408, 429, 500, 502, 503, 504]
  idempotent_write:
    max_attempts: 3
    max_wait_seconds: 120
    retry_statuses: [408, 429, 502, 503, 504]
  uncertain_write:
    max_attempts: 1
    max_wait_seconds: 0
    retry_statuses: []
shared_scope:
  max_delayed_requests: 25
  max_concurrent_requests: 2

Этот фрагмент предотвращает знакомый сбой: агент получает тайм-аут после отправки записи, решает, что ничего не произошло, и повторяет запрос к provider-у, который уже испытывает нагрузку. Класс uncertain_write вместо этого заставляет проверить статус или передать задачу на эскалацию. Он не вознаграждает настойчивость, если настойчивость меняет результат.

Бюджет должен учитывать каждую фактическую попытку, включая повторы, запущенные библиотеками. Я видел, как в приложении объявляли управление повторами, а HTTP-клиент, runner рабочих процессов и proxy каждый повторял запрос ниже этого уровня. Итоговое число запросов казалось загадочным, пока кто-то не изучил все три набора значений по умолчанию. Выберите один уровень, который отвечает за повторы. Настройте все остальные так, чтобы они передавали ошибки выше без повторов, либо явно опишите их поведение и включите его в общий бюджет.

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

Для backoff нужны jitter и верхний предел

Экспоненциальная задержка снижает нагрузку после повторных отказов, увеличивая интервал между попытками. Jitter не даёт множеству workers, одновременно завершивших работу с ошибкой, вернуться одной синхронной волной. Оба механизма нужны на стороне client, даже если provider публикует время сброса: внутренняя параллельность сама может создать лавину запросов.

Для попытки n, где первый повтор имеет номер n = 1, вычислите предел и выберите случайную задержку внутри него:

import random

BASE_SECONDS = 1.0
MAX_SECONDS = 60.0

def retry_delay(attempt_number: int) -> float:
    cap = min(MAX_SECONDS, BASE_SECONDS * (2 ** attempt_number))
    return random.uniform(0, cap)

Это полный jitter. Он не даёт каждому worker ждать ровно 2, 4, 8 и 16 секунд. Одинаковые фиксированные задержки популярны, потому что делают журналы понятными. Но по ним легко предсказать скоординированные повторы, а это противоположно тому, что нужно загруженному service.

Если ответ содержит Retry-After, это значение имеет приоритет над локально рассчитанной более короткой задержкой. RFC 9110 допускает Retry-After в виде числа секунд или даты HTTP. Разбирайте оба варианта. Если дата уже прошла из-за различий в часах машины и provider-а, применяйте небольшую минимальную задержку, а не запускайте плотный цикл повторов.

Не используйте backoff вместо регулирования частоты. Backoff начинается после сбоя. Token bucket, leaky bucket или простой лимит планировщика управляют скоростью до сбоя. Если provider разрешает известное число запросов за известный интервал, отправляйте запросы медленнее опубликованного лимита и оставляйте запас для интерактивной работы. Планировщик также должен ограничивать параллельность. Двадцать одновременных запросов могут израсходовать ёмкость короткого интервала ещё до того, как worker прочитает ответ RateLimit-Remaining.

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

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

Идемпотентность определяет безопасность повтора

Идемпотентный запрос имеет один и тот же ожидаемый эффект при повторной отправке. Это не значит, что любой запрос с HTTP PUT безвреден в каждом приложении, и не значит, что любой POST опасен. RFC 9110 описывает такие методы, как PUT и DELETE, как идемпотентные по намерению, тогда как POST обычно идемпотентным не считается. Операционный риск определяется реальным контрактом API provider-а.

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

В этой области часто смешивают два разных состояния:

• Запрос, который точно не дошёл до provider-а, можно отправить снова, если сама операция это допускает.
• Запрос с неизвестным результатом требует сверки до того, как агент отправит ещё один запрос с побочным эффектом.

Сбой соединения после того, как client записал байты, не доказывает, что provider не выполнил действие. Server мог завершить операцию и потерять соединение с ответом. Агент не может вывести результат из одного лишь отсутствия ответа.

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

POST /v1/transfers HTTP/1.1
Idempotency-Key: transfer-7c41b5b9-7f5b-4f51
Content-Type: application/json

{"source":"acct_17","destination":"acct_42","amount":12500,"currency":"USD"}

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

Если в API нет функции идемпотентности, ищите схему «создать, затем запросить». Агент может добавить в тело созданную client-ом внешнюю ссылку, а после неопределённого сбоя выполнить поиск по этой ссылке. Если в API нет ни идемпотентности, ни надёжного поиска, не автоматизируйте повторную запись. Попросите человека проверить записи provider-а. Это кажется медленнее, пока первый дублированный побочный эффект не попадёт в систему, где его нельзя аккуратно отменить.

Отделяйте лимиты частоты от сбоев service и неправильных запросов

Политика, которая одинаково обрабатывает все ответы, отличные от успешных, скрывает дефекты и расходует квоту. Перед выбором задержки классифицируйте ответ. Важны код статуса, тело ответа, код ошибки provider-а и метод запроса.

Используйте такое практическое разделение:

• 429 означает снизить темп, соблюдать указания provider-а и списать запрос из общего бюджета ограничения частоты.
• 408, сброс соединения и некоторые ответы 5xx могут допускать ограниченный повтор, но для операций записи всё равно нужен путь идемпотентности или сверки.
• 400, 401, 403, 404 и 422 обычно требуют исправить запрос, изменить авторизацию или принять решение человеку. Повторять их бессмысленно.
• 409 требует обработки с учётом ресурса. Это может быть дубликат, конфликт версии или блокировка другого рабочего процесса.
• Специфическая ошибка provider-а об исчерпании квоты может означать ожидание расчётного или суточного сброса, что отличается от короткого лимита на всплеск.

Не считайте 503 Service Unavailable взаимозаменяемым с 429. 503 говорит, что service сейчас не может обслужить запрос; 429 означает, что client превысил лимит. Оба ответа могут содержать Retry-After, но 429 должен заставить планировщик уменьшить локальную пропускную способность для затронутой области. 503 может быть региональным, относиться к конкретному endpoint или ко всему provider-у. Сохраняйте это различие в метриках и сообщениях для операторов.

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

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

Для общих учётных данных нужна одна очередь, а не вежливые агенты

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

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

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

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

Лимиты часто показывают более глубокую проблему планирования. Агент, который вызывает endpoint деталей один раз для каждого объекта, может точно следовать инструкции, но использовать неправильный способ доступа. До добавления повторов проверьте пакетные endpoint-ы, управление пагинацией, условные запросы, webhooks, задачи экспорта или серверный поиск. Такие изменения уменьшают число вызовов ещё до того, как provider начнёт их отклонять.

Sallyport может хранить API-учётные данные вне процесса агента и записывать отдельные исходящие вызовы, но caller всё равно нужны очередь и управление повторами. Разделение учётных данных уменьшает риск утечки секретов, но не меняет квоту provider-а.

Эскалация человеку должна сохранять неопределённость

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

Передайте оператору следующие сведения:

• желаемый результат задачи и точное логическое действие, на котором она остановилась;
• provider, endpoint, метод, область аккаунта и очищенный отпечаток запроса;
• время попыток, статусы, заголовки Retry-After или лимитов и израсходованный бюджет;
• есть ли у операции токен идемпотентности, идентификатор операции provider-а или запрос сверки;
• безопасные варианты продолжения: подождать, запросить статус, увеличить квоту, изменить план или отменить.

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

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

Одобрение продолжения доступа и одобрение конкретного внешнего действия это разные меры контроля. Сессия может оставаться авторизованной, но агенту всё равно может требоваться проверка каждого вызова для платежа, записи в production или повторного запроса после события ограничения. Храните эти решения раздельно и в интерфейсе, и в журнале.

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

Аудит должен объяснять и попытку действия, и ожидание

Полезная запись аудита отвечает не только на вопрос «вернулся ли 200?». В ней должно быть видно, что агент пытался сделать, какая авторизация это разрешила, что вернул удалённый service и как контроллер повторов отреагировал. Без записи решения последовательность вызовов может выглядеть небрежным повторением, даже если планировщик соблюдал документированный Retry-After.

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

14:11:02 action_requested  task=sync-482 method=POST route=/records
14:11:02 action_sent       attempt=1 idempotency=rec-91f2
14:11:03 action_result     status=429 retry_after=30 scope=account:ops
14:11:03 retry_scheduled   attempt=2 due=14:11:33 budget_wait=30
14:11:33 action_sent       attempt=2 idempotency=rec-91f2
14:11:34 action_result     status=201 provider_id=r_893

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

Защита журналов от незаметного изменения полезна при разборе инцидента: команда может проверить, что после события не были удалены неудобные попытки. Sallyport формирует журналы сессий и вызовов из зашифрованного аудита с хеш-цепочкой, а sp audit verify проверяет цепочку автономно, без ключа хранилища. Это помогает оператору отличить ограничение со стороны provider-а от цикла агента или позднего ручного повтора.

Журналам также нужны сроки хранения и границы доступа. Путь запроса, идентификатор аккаунта provider-а и временной рисунок могут раскрывать чувствительную операционную активность, даже если сам токен нигде не появляется. Сохраняйте достаточно данных для восстановления решения, а затем ограничивайте круг тех, кто может искать и экспортировать записи.

Проверяйте пути сбоев до того, как агент найдёт их в production

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

Выполните такую последовательность в тестовой среде или против управляемого поддельного API:

1. Запустите три задачи агентов, использующие одну смоделированную область аккаунта и отправляющие один и тот же безопасный запрос чтения.
2. Верните 429 с Retry-After: 10 для первого запроса и проверьте, что планировщик задерживает всю работу в этой области, не позволяя двум другим запросам продолжаться на полной скорости.
3. После задержки верните успешный ответ и проверьте, что время повторов немного различается, а запросы не приходят одной волной.
4. Отправьте запись со стабильным ключом идемпотентности, смоделируйте разрыв соединения после того, как поддельный API сохранил запись, и проверьте, что runner запрашивает статус, а не создаёт новую запись.
5. Исчерпайте настроенный бюджет времени и убедитесь, что оператор получает очищенную запись эскалации, а отменённая работа не просыпается позже.

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

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

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