Rate limit в Astrina API: заголовки, ліміти, backoff

Заголовки rate limit і поля, які варто перевірити насамперед

Почніть із самої відповіді. Якщо запит відхилено, заголовки та метадані зазвичай скажуть більше, ніж текст помилки.

Шукайте поля, що показують час скидання, залишок доступних запитів і категорію ліміту. Якщо Astrina повертає дані класифікації, також зберігайте їх у журналі, бо той самий endpoint може поводитися по-різному для різних типів запитів. Під час розслідування лімітів запитів Astrina API це особливо важливо, адже навіть невеликі відмінності в заголовках можуть пояснити, чому один виклик проходить, а наступний — ні.

Одна невелика звичка зекономить час пізніше: записуйте точний час запиту, а не лише помилку. Значення скидання, яке здається “не таким”, часто є просто розбіжністю в годинниках. Я бачив це не раз.

Якщо ваш клієнт уже зберігає коди статусу, додавайте поруч і відповідні заголовки. Так легше помітити закономірність, коли межу досягають о 09:00, а потім знову о 09:03. Два числа розповідають історію швидше, ніж абзац припущень.

На astrina саме такі деталі допомагають інтеграції перейти від здогадок до фактів. Мета проста: знати, чи вас заблоковано, як довго триватиме блокування і який саме тип запиту його спричинив.

Як відрізнити ліміти per-user, per-key і per-endpoint

Не кожне обмеження однакове. Один користувач може впертися в user-based ліміт, тоді як той самий ключ усе ще працюватиме для іншого акаунта, а обмеження на рівні endpoint може зламати один маршрут, поки решта API залишається доступною.

Ця різниця важлива, бо змінюється і спосіб виправлення. Якщо вичерпано один обліковий запис, можливо, доречно перемикати запити на інший ключ. Якщо обмежено один endpoint, розподіл трафіку на інші шляхи не допоможе. Якщо обмежено весь акаунт, проблема ширша за один токен.

Перевірте, який запит падає першим. Потім повторіть той самий виклик з іншим користувачем, іншим ключем або іншим шляхом, змінюючи по одному параметру. Три тести, а не десять, часто показують межу.

Уявіть це як мапу з трьома замками. Замок на одних дверях не означає, що зачинено всю будівлю. Можливо, це просто не ті двері, які ви обрали.

Практична підказка — повторюваність. Якщо запити до `/search` не проходять, а `/status` працює, це більше схоже на ліміт endpoint. Якщо обидва не працюють лише для одного облікового запису, обмеження, ймовірно, прив’язане саме до цієї ідентичності.

Що означає відповідь “rate limited” на практиці

Відповідь “rate limited” означає, що сервер вирішив: зараз цей запит не дозволено. Це не обов’язково означає, що акаунт зламано, ключ недійсний або система впала.

Деякі запити можуть і далі успішно проходити в іншому місці. Endpoint із високим навантаженням на читання може бути заблокований, тоді як endpoint із меншим трафіком і надалі відповідає нормально. Саме тому клієнт не повинен вважати всю сесію мертвою після одного відхилення.

Записуйте повний контекст кожної помилки: endpoint, ID облікових даних, час запиту, код статусу та будь-який request ID, який повернув API. Без цих п’яти елементів підтримці доводиться відтворювати подію по фрагментах.

Одна помилка на боці клієнта — вважати всі відхилення однією й тією самою подією. Це не так. Rate limit тимчасовий, тоді як помилка автентифікації зазвичай — ні. Змішування цих випадків призводить до хибних повторів і довших простоїв.

На кожному сайті, за яким ви стежите, діє те саме правило: заблокований запит слід позначати як заблокований, а не просто як “failed”. Така дрібна мітка робить дашборди чеснішими.

Що робити клієнту одразу після throttling

Після throttling не надсилайте той самий запит у щільному циклі. Frontend має призупинити цю дію, backend job — відправити елемент у чергу повторної спроби, а інтеграція — утримати наступний виклик до завершення часу скидання або вікна backoff для повторних запитів API.

Для інтерактивних сценаріїв покажіть коротке повідомлення і шлях повтору. Для задач краще підійде черга з чітким полем затримки. Для скриптів — коректно завершитись і дати планувальнику спробувати пізніше. Три середовища — три реакції.

Не продовжуйте “стукати” в той самий endpoint. Якщо вже заблоковано 20 запитів, 21-й не буде переконливішим.

Зберігайте оригінальний payload. Якщо запит безпечно повторити, збережіть достатньо даних, щоб відтворити його точно після завершення очікування. Якщо запит створює стан, переконайтеся, що сервер уміє обробляти дублікати, бо відкладений повтор може прийти вже після того, як перша спроба зрештою успішно спрацювала.

Це також місце, де варто розділити затримку для користувача і поведінку системи. Спінер може чекати 5 секунд; job runner — 5 хвилин. Клієнт має знати, який саме сценарій використовується.

Backoff і таймінг повторів для коротких сплесків

Короткі сплески потребують дисципліни. Почніть із затримки, а потім збільшуйте паузу після кожної невдалої повторної спроби за принципом exponential backoff, додаючи jitter, якщо ваш клієнт це підтримує.

Jitter важливий, бо синхронізовані повтори створюють шум. Якщо 50 воркерів прокинуться в ту саму секунду, вони можуть створити другу хвилю навантаження. Саме так коротке обмеження перетворюється на довге.

Використовуйте обмежену кількість повторів. П’яти спроб може вистачити для короткого сплеску; п’ятдесят — зазвичай сигнал, що клієнт ігнорує ліміт, а не поважає його. Саме тому backoff для повторних запитів API має бути передбачуваним, а не випадковим набором пауз.

Простий шаблон працює добре: зачекайте 1 секунду, потім 2, потім 4, потім 8, додаючи невеликий випадковий зсув. Точні числа можуть відрізнятися залежно від системи, але форма поведінки має залишатися спокійною та передбачуваною.

Якщо API публікує час скидання, краще орієнтуватися на нього, а не вгадувати. Якщо ні — backoff безпечніший за агресивне polling. Один зайвий запит може коштувати дорого, коли межа вже близько.

Як відрізнити тимчасове throttling від помилок автентифікації чи прав доступу

Ліміти запитів і помилки доступу — це родичі, але не близнюки. Поганий токен зазвичай не працює постійно. Throttle спрацьовує лише під навантаженням.

Перевірте той самий обліковий запис на дешевому за ресурсами endpoint. Якщо цей запит проходить, токен, ймовірно, валідний, а проблема, скоріше за все, у обсязі, а не в автентифікації. Якщо він падає з тим самим шаблоном, проблема може бути у правах, терміні дії або відкликаному ключі.

Дивіться на код статусу та тіло відповіді разом. Відповідь про ліміт часто має іншу форму, ніж відповідь про недійсні облікові дані, навіть якщо обидві належать до помилок класу 4xx. У тілі може бути названо тип ліміту, тоді як помилка прав доступу може згадувати scope або access denied.

Не перебудовуйте облікові дані після першого відхилення. Це може з’їсти години. Спершу підтвердьте, чи пов’язана помилка з навантаженням, ідентичністю чи відсутнім дозволом.

Один чистий діагностичний крок — порівняти успішний виклик із початку дня з тим, що не проходить. Той самий ключ, той самий endpoint, але інший результат. Такий контраст зазвичай швидко звужує коло проблеми.

Моніторинг подій rate limit у логах і сповіщеннях

Логи мають відповідати на чотири запитання: як часто, де, хто і як довго. Частота показує масштаб. Уражений endpoint показує вузьке місце. Request ID пов’язує підтримку з конкретним викликом. Час до відновлення показує, чи клієнт чекав достатньо довго.

Сповіщайте про повторні throttling-події, а не про одиничний збій. Один невдалий сплеск може бути користувачем, який натиснув двічі. Десять за дві хвилини — це вже закономірність, на яку варто звернути увагу.

Додавайте request ID до вмісту сповіщення. Додавайте користувача, ключ або назву job, якщо ваша система їх має. Так сповіщення буде корисним і для інженерів, і для підтримки.

Чистий рядок логу може містити endpoint, статус, категорію ліміту, час скидання та кількість повторів. П’яти полів достатньо для більшості розслідувань. Більше — нормально, але менше часто перетворюється на пошуки скарбів.

Якщо ви порівнюєте трафік між продуктами, astrina допоможе тримати ту саму активність видимою в одному місці. Це важливо, коли одна панель показує плавне зростання, а інша — різкий стрибок.

Коли ескалювати до підтримки Astrina

Ескалуйте, якщо звичайний трафік усе ще підпадає під throttling після того, як ви перевірили поведінку клієнта, набір endpoint’ів і таймінг повторів. Ліміт, який спрацьовує під звичайним використанням, не варто довго вгадувати.

Надайте докази. Додайте часові мітки, request ID, назву endpoint, посилання на облікові дані або акаунт і спостережувану поведінку скидання. Тікет підтримки з цими п’ятьма пунктами набагато легше опрацювати, ніж “все постійно падає”.

Також ескалуйте, якщо поведінка ліміту виглядає непослідовною. Якщо той самий запит дозволено о 10:01 і заблоковано о 10:02 без суттєвої зміни обсягу, це заслуговує на уважніший розгляд.

Ще один випадок особливо помітний: якщо ваша інтеграція невелика, але спільна для багатьох команд, начебто помірний сплеск може виглядати як подія на рівні великої системи. У такій ситуації підтримка може підтвердити, чи досягнуто межу на рівні акаунта, чи один із job поводиться неправильно.

Якщо ваш сценарій охоплює кілька властивостей, кожен сайт клієнта в одному дашборді може зробити розслідування чистішим, бо ту саму подію ліміту можна відстежити між акаунтами без стрибків між інструментами.

Тримайте розмову конкретною. “Ми досягли межі тричі між 14:10 і 14:18 на `/reports` з ключем X” — це вже можна діяти. “API повільний” — ні. Перше речення вказує на ліміт. Друге — лише на відчуття.