В шлюзе API для одного клиента настроено ограничение запросов:
HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 3
Какой механизм управления нагрузкой стоит за таким ответом и как он должен работать?
Это ограничение частоты запросов (rate limiting): шлюз контролирует объём запросов клиента за интервал или с помощью «ведра токенов» и временно отклоняет превышение лимита. Код 429 сообщает, что запрос отклонён именно из-за превышения допустимой частоты, а Retry-After: 3 указывает клиенту подождать три секунды перед повторной попыткой.
Клиент не должен немедленно повторять запросы: это продлевает перегрузку и может привести к лавине повторных обращений. Для автоматических повторов применяют задержку, экспоненциальный backoff и случайный разброс задержки (jitter).
Ограничение частоты появилось как практический способ защитить сервисы от неравномерной нагрузки, ошибок клиентов и злоупотреблений. Без него один клиент или неисправный цикл повторов может занять непропорциональную долю соединений, процессорного времени, памяти или лимитов внешней системы.
Изначально лимиты часто задавались простым числом запросов за временное окно. На практике потребовались более гибкие алгоритмы: они сглаживают пики, учитывают разные классы клиентов и позволяют отдельно ограничивать дорогие операции.
Допустим, клиенту разрешено 100 запросов, но он отправляет 500 почти одновременно. Если шлюз пропустит всё, downstream-сервис может исчерпать пул соединений или начать отвечать с ошибками. Если шлюз просто закроет соединение без понятного сигнала, клиент не сможет отличить ограничение от сетевого сбоя и выберет неподходящую стратегию повтора.
Важно определить, к чему применяется лимит: к IP-адресу, API-ключу, пользователю, организации, маршруту или их комбинации. Лимит по IP может несправедливо объединить многих пользователей за одним NAT, а лимит только по клиенту может не защитить конкретный дорогой endpoint.
Шлюз хранит состояние потребления квоты и перед обработкой запроса проверяет, разрешён ли ещё один вызов. В варианте фиксированного окна считается число запросов внутри интервала; в варианте скользящего окна учитываются более точные временные границы; в алгоритме token bucket токены поступают с заданной скоростью и расходуются по одному или нескольку на запрос.
RateLimit-Limit обозначает установленную квоту, RateLimit-Remaining — доступный остаток, а RateLimit-Reset — ориентир до восстановления квоты. При превышении шлюз возвращает 429 Too Many Requests; Retry-After задаёт рекомендуемое время ожидания. Эти поля являются подсказкой клиенту, но не заменяют серверную проверку лимита.
Для распределённого шлюза состояние лимита должно быть согласовано между экземплярами либо запросы должны предсказуемо маршрутизироваться к одному узлу. Локальный счётчик на каждом экземпляре может фактически умножить разрешённую квоту на количество узлов. Централизованное хранилище даёт более точный результат, но добавляет задержку и само становится зависимостью.
Следует различать ограничение частоты и ограничение параллелизма. Rate limiting контролирует число запросов во времени, а concurrency limit — количество одновременно выполняющихся операций. Для длинных или дорогих запросов одного временного лимита недостаточно.
Повторять автоматически можно не любой запрос. Для безопасных или идемпотентных операций это обычно проще; для операций, создающих побочный эффект, клиент должен учитывать возможность того, что сервер уже принял запрос, но ответ потерялся. Также нельзя безусловно повторять запросы всех клиентов одновременно после истечения Retry-After, иначе возникнет синхронный всплеск.
Минимальный пример реакции клиента на такой ответ:
Клиент читает Retry-After, ждёт указанное время с добавленным случайным смещением и только затем решает, делать ли повтор. Шлюз при этом продолжает независимо проверять квоту каждого нового запроса.
Лимиты должны быть наблюдаемыми: полезно измерять долю ответов 429, распределение остатка квоты, задержки, отказавшие маршруты и клиентов, систематически достигающих лимита. Само наличие заголовков не гарантирует справедливость или защиту: алгоритм, ключ группировки и хранилище состояния являются частью решения.
Партнёрский клиент массово импортирует данные, а интерактивные запросы пользователей начинают получать тайм-ауты. Рассматривались три варианта. Полный запрет импорта быстро освобождал ресурсы, но нарушал бизнес-процесс; фиксированное окно было простым, однако создавало всплеск на границах интервалов; отдельные лимиты по API-ключам не учитывали, что импорт и пользовательские запросы конкурируют за один дорогой маршрут.
Выбрали token bucket с отдельной квотой для импорта, ограничением параллельных тяжёлых операций и очередью для фоновых задач. Интерактивному трафику выделили более высокий приоритет, а клиенту импорта стали возвращать 429 с рекомендацией повторить позже. В результате кратковременные пики перестали блокировать пользовательские запросы, а импорт сохранил предсказуемую, хотя и меньшую, пропускную способность.
1. Достаточно ли возвращать 429 без Retry-After?
Нет, такой ответ сообщает факт ограничения, но не рекомендует момент повтора. Клиенту придётся использовать собственную стратегию, которая может быть слишком агрессивной или чрезмерно консервативной. Даже с Retry-After клиенту нужен верхний предел числа повторов и обработка ситуации, когда лимит продолжает превышаться.
2. Почему счётчик в памяти одного экземпляра шлюза может быть ошибочным?
При нескольких экземплярах каждый узел видит только часть запросов и применяет собственную квоту. Если балансировщик распределяет трафик равномерно, суммарно клиент получит примерно столько квот, сколько экземпляров, что нарушит заявленный лимит. Общий атомарный счётчик или согласованный распределённый алгоритм исправляет проблему, но повышает стоимость координации и требования к отказоустойчивости.
3. Чем опасен лимит только по IP-адресу?
Многие реальные пользователи могут иметь один внешний IP через NAT, прокси или корпоративный шлюз. Один активный клиент тогда способен исчерпать общую квоту и ухудшить обслуживание остальных. Обычно используют идентичность клиента, API-ключ или арендатора, но эти признаки должны быть надёжно установлены до применения лимита; часто добавляют и отдельный защитный лимит по IP.