429 Too Many Requests: лимиты запросов, Retry-After и ложные тревоги

Что означает 429 и что приходит вместе с ним

Код 429 определен в RFC 6585 как статус ограничения частоты: клиент отправил слишком много запросов за отведенное время. Спецификация намеренно оставляет открытыми две вещи: как сервер опознает клиента и как он считает запросы. Поэтому ограничения так сильно различаются между сервисами.

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

В ответе приходят нужные вам сигналы:

• Retry-After это стандартный из них. RFC 9110 разрешает и число секунд, и дату в формате HTTP, и корректный клиент выжидает это время перед повтором.
• Заголовки лимитов вроде RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset или их более старые варианты с префиксом X-RateLimit- показывают бюджет и момент его сброса. Это соглашения, а не часть RFC 9110, поэтому точные имена смотрите в документации API.
• Тело ответа должно объяснять ограничение человеческим языком. Многие API называют превышенную квоту, что избавляет от долгих догадок.

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

Ограничение частоты или настоящий сбой?

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

• Сам код. Ограничение частоты отвечает 429. Перегруженный сервер или сервер на техработах отвечает 503. Оба могут нести Retry-After, отсюда и путаница, но смысл разный: 429 говорит «именно вы шлете слишком много», а 503 говорит «сервис целиком сейчас не может брать работу». Про вторую сторону читайте в руководстве по 503.
• Время ответа. Ограничения отказывают быстро, обычно за миллисекунды, потому что решение принимается до всякой настоящей работы. Перегрузка отвечает медленно или не отвечает вовсе.
• Кого задело. Ограничение бьет по одной клиентской личности. Проверьте с другого IP-адреса или с другим ключом API: если там проходит, а у придушенного клиента нет, это лимит, а не сбой.
• Картина во времени. Ограничение периодично и снимается само. Отказы идут пачкой, прекращаются ровно на сбросе окна и потом возвращаются. Сбой не возобновляется вежливо по расписанию.
• Связь с вашим собственным объемом. Если отказы начались, когда вы участили проверки, добавили параллельных воркеров или запустили пакетную задачу, причина на вашей стороне соединения.

Почему мониторинг может сам вызвать 429

Мониторинг это повторяющийся запрос с небольшого набора адресов к одному и тому же URL, а именно такую форму ограничители и учатся ловить. Очень короткий интервал проверки усугубляет это, потому что ежеминутные проверки, умноженные на множество адресов, быстро съедают бюджет на один IP. То же делает запуск проверки сразу из многих локаций: источник видит всплеск вместо ровного ручейка, а лимиты на всплеск срабатывают первыми.

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

Как починить 429

1. Прочитайте заголовки ответа, прежде чем что-либо менять:

   curl -sS -o /dev/null -D - https://example.com/api/items

   Retry-After и заголовки лимитов называют реальный бюджет, а это лучше догадок про интервалы.
2. Соблюдайте Retry-After. Немедленный повтор во многих реализациях продлевает блокировку. Выждите указанное время.
3. Отступайте экспоненциально и с разбросом в клиентском коде, чтобы параллельные клиенты не синхронизировались и не пошли на повтор толпой.
4. Снизьте частоту запросов. Для мониторинга переведите проверяемый адрес на более длинный интервал или разнесите проверки, чтобы множество локаций не стреляло в одну и ту же секунду.
5. Проверяйте дешевый представительный URL. Легкий адрес состояния или главная страница скажут вам, что сайт работает, не тратя квоту, которая нужна реальному трафику.
6. Исключите клиента мониторинга на самом ограничителе. Внесите адреса точек проверки в белый список или выдайте мониторингу собственный ключ API с собственным бюджетом, чтобы он никогда не соревновался с боевым трафиком.
7. Если ограничитель ваш, проверьте, верен ли лимит. Спросите себя, соответствует ли бюджет реальному использованию, не считается ли он по IP там, где должен считаться по аккаунту, и не сидит ли за одним адресом множество пользователей из-за общего прокси или корпоративного NAT.

Как следить за 429, не вызывая их

Ограничения обычно раньше всех настигают самых активных клиентов, то есть платящих заказчиков и интеграции, а не вашу команду. Проверка HTTP по расписанию со сверкой ожидаемого кода состояния показывает 429 как отдельное событие с отметкой времени, а не как разрозненные жалобы на то, что «API барахлит», и по времени видно, периодичен лимит или постоянен. Интервал задавайте осознанно: достаточно часто, чтобы быстро заметить проблему, и достаточно мягко, чтобы сама проверка никогда не била в лимит. Более широкое семейство отказов, включая 401 и 403, разобрано в обзоре 4xx.