Ошибка 429 Too Many Requests

HTTP 429 Too Many Requests означает, что клиент отправил слишком много запросов за некоторый период и попал под ограничение частоты. Это механизм rate limiting: сервер просит конкретного клиента, пользователя, токен или другой идентификатор снизить интенсивность обращений.

429 не равен «сервер перегружен вообще». Для общей временной неготовности сервиса чаще подходит 503 Service Unavailable. При 429 ключевой вопрос: какой лимит сработал, по какому ключу он считается и когда можно безопасно повторить запрос.

Что означает HTTP 429

клиент
  ↓ запросы
1 2 3 4 5 ... N
  ↓
rate limiter
  ↓ лимит превышен
429 Too Many Requests
Retry-After: ...

RFC 6585 определяет 429 как ответ на слишком большое число запросов за заданный период. Ответ может содержать Retry-After, указывающий, сколько ждать до следующей попытки.

Где может находиться rate limiter

Ограничение может применяться на разных уровнях:

• CDN;
• WAF;
• API gateway;
• reverse proxy;
• приложение;
• внешний API;
• отдельный tenant/user/token;
• IP или подсеть.

Поэтому сообщение «API возвращает 429» ещё не указывает, кто именно ввёл лимит.

429 и 503

Если все пользователи одновременно получают 503, это другой класс проблемы, чем один интеграционный токен, который получил 429.

Шаг 1. Сохраните headers и body

curl -i https://api.example.com/v1/items

Смотрите:

• Retry-After;
• request ID;
• provider-specific rate-limit headers, если они документированы;
• JSON error code;
• response server/edge headers.

Не полагайтесь на нестандартный header, если он не описан контрактом конкретного API.

Retry-After

Заголовок может задавать задержку в секундах или HTTP-date:

Retry-After: 120

или:

Retry-After: Wed, 26 Aug 2026 12:00:00 GMT

Если API прислал Retry-After, клиенту нужно учитывать его, а не продолжать агрессивный retry.

Шаг 2. Определите ключ лимита

Возможные варианты:

IP
user ID
API token
tenant
endpoint
глобальный client ID

Если два разных токена с одного IP ведут себя одинаково, возможен IP-based limit. Если ограничен только один токен — вероятен per-token/per-account limit. Это диагностические признаки, а не универсальное правило: источник истины — документация и конфигурация конкретного сервиса.

Шаг 3. Измерьте фактическую интенсивность

Нужно знать не «мы отправляем немного запросов», а конкретные параметры:

requests/second
requests/minute
concurrency
burst size
количество worker
retry count

Частая причина — несколько worker считают себя единственным клиентом:

10 worker × 20 req/s = 200 req/s

хотя лимит рассчитан на 100 req/s.

Шаг 4. Проверьте retry storm

Опасная схема:

429
→ немедленный retry
→ ещё 429
→ несколько worker повторяют
→ ещё больше запросов

Правильная стратегия зависит от API, но обычно включает:

• уважение Retry-After;
• ограниченное число повторов;
• backoff;
• jitter для распределения повторов;
• общий rate limiter между worker;
• idempotency для state-changing операций.

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

Шаг 5. Проверьте burst, а не только среднее

Среднее 10 req/s не исключает burst:

0 req
0 req
0 req
100 req за одну секунду

Token bucket или другое окно может ограничить такой всплеск, хотя минутное среднее выглядит приемлемо.

Шаг 6. Определите, кто вернул 429

Сопоставьте:

время
request ID
edge log
gateway log
application log

Если приложение не видит запросы, rate limiter находится раньше.

Если public URL даёт 429, а допустимый прямой upstream в диагностической среде — нет, проверяйте gateway/edge policy.

429 во внешнем API

Если лимит установлен сторонним провайдером, не пытайтесь «исправить сервер». Нужно:

1. прочитать официальные лимиты;
2. уменьшить частоту;
3. использовать batching/caching;
4. объединить запросы;
5. синхронизировать worker;
6. корректно обрабатывать Retry-After;
7. при необходимости изменить квоту только если это действительно требуется.

429 после релиза

Проверьте:

• новый polling;
• дублирующиеся background jobs;
• цикл retry;
• уменьшившийся client cache;
• fan-out;
• новый frontend запрос;
• изменение числа replicas;
• исчезнувший distributed limiter.

Резкий рост 429 часто показывает не падение сервиса, а изменение паттерна нагрузки клиента.

Как проверить восстановление

До исправления:

burst → 200, 200, 429, 429...

После исправления:

контролируемая частота → стабильные ожидаемые ответы
при сознательном превышении → 429
после Retry-After → запрос снова разрешён

Не пытайтесь доказать исправление нагрузочным тестом на production без согласованной процедуры.

429 и мониторинг

Если мониторинг сам слишком часто вызывает ограниченный endpoint, он может создавать ложный инцидент. Интервал проверки должен учитывать API contract и quota.

Для критичного API полезно отличать:

• неожиданный 429 при обычной частоте;
• ожидаемый 429 в тесте лимита;
• 503 общей недоступности;
• рост latency до отказа.

UpWatch можно использовать для регулярного контроля API endpoint с безопасной частотой и заранее заданным ожидаемым результатом.

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

• мгновенно повторять 429;
• игнорировать Retry-After;
• путать 429 и 503;
• считать только средний RPS;
• забывать сумму нагрузки всех replicas;
• повышать quota вместо устранения retry loop;
• делать нагрузочный тест на production без контроля.

Практический чек-лист

1. Подтвердить HTTP 429.
2. Сохранить response headers/body.
3. Проверить Retry-After.
4. Определить компонент rate limiting.
5. Определить ключ лимита.
6. Измерить общий RPS/concurrency.
7. Проверить burst.
8. Проверить retries.
9. Синхронизировать worker.
10. Ввести backoff согласно контракту.
11. Проверить идемпотентность.
12. Подтвердить восстановление безопасной серией запросов.

Источники и спецификации

• RFC 6585: 429 Too Many Requests
• RFC 9110: Retry-After
• MDN: 429 Too Many Requests
• curl: официальная документация