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, що близько до форми, яку обмежувачі швидкості й покликані ловити. Дуже короткий інтервал перевірки погіршує це, бо щохвилинні перевірки, помножені на багато моніторингованих URL, швидко додаються до бюджету на одну IP-адресу. Так само і запуск перевірки з багатьох локацій одночасно: джерело бачить сплеск, а не рівномірний потік, а обмеження сплесків спрацьовує першим.

Вибір URL теж має значення. Сторінки пошуку, ендпоінти 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.