agentsready
API / Auth / MCP Легко

RateLimit-заголовки: дайте агентам тормозить вежливо

Что такое стандартные RateLimit-заголовки, зачем они AI-агентам, минимальный пример, правильно vs неправильно, ошибки и как проверить.

Обновлено:

Что это

Стандартные RateLimit-заголовки (IETF draft) сообщают клиенту его квоту прямо в ответе: сколько запросов осталось и когда счётчик сбросится. Современная форма — структурное поле RateLimit (с параметрами limit, remaining, reset); раньше использовались три отдельных заголовка RateLimit-Limit/-Remaining/-Reset.

Зачем это AI-агентам

Агент-автомат не «чувствует» нагрузку, как человек. Без явной квоты он либо долбит ваш сервер, либо натыкается на жёсткий блок (429) и падает. Машиночитаемый лимит позволяет агенту тормозить заранее и вежливо: видит remaining: 2 — сбавляет темп. Это и защита сервера, и предсказуемая автоматизация для клиента.

Минимальный рабочий пример

Современная (структурная) форма:

HTTP/1.1 200 OK
RateLimit: limit=100, remaining=87, reset=42
RateLimit-Policy: 100;w=60

При превышении:

HTTP/1.1 429 Too Many Requests
RateLimit: limit=100, remaining=0, reset=30
Retry-After: 30

Правильно vs неправильно

ПравильноНеправильно
RateLimit с limit/remaining/reset на ответахНет заголовков — агент узнаёт лимит только по 429
Retry-After на 429429 без подсказки, когда повторить
reset отражает реальное окноСлучайные/неверные значения
Консистентно на всех лимитируемых ручкахТолько на части эндпоинтов

Типичные ошибки

  • Только 429 без RateLimit-заголовков — агент бьётся вслепую.
  • Нет Retry-After на 429 — клиент не знает паузу.
  • Неверный reset (не то окно/единицы) — агент тормозит не вовремя.
  • Смешение старого и нового формата без согласованности.

Как проверить

Скан проверит наличие RateLimit-заголовков. Вручную:

curl -sI https://example.com/api/endpoint | grep -i 'ratelimit\|retry-after'

Ждём RateLimit: (или RateLimit-*) на обычном ответе и Retry-After на 429.

Источники