Telm вимірює API двома способами: похвилинним лімітом частоти (стеля сплеску) та денною квотою (ваш загальний бюджет на добу за UTC). Обидва масштабуються з тарифом. Кожна виміряна відповідь повертає X-Quota-Limit, X-Quota-Used та X-Quota-Reset, тож ви завжди знаєте свій залишковий бюджет, і обидва ліміти повертають 429 із заголовком Retry-After при перевищенні.
1Два ліміти: похвилинна частота та денна квота
Є дві окремі стелі. Похвилинний ліміт частоти обмежує, скільки запитів ви можете зробити протягом будь-якої однієї хвилини, згладжуючи сплески. Денна квота — це ваш загальний бюджет: вона обмежує, скільки виміряних викликів ви можете зробити за всю добу UTC.
Вони незалежні. Ви можете досягти похвилинного ліміту, ще маючи вдосталь денної квоти (ви просто надсилаєте надто швидко), або вичерпати денну квоту, будучи значно нижче похвилинного ліміту (ви використали день). Обидва повертають статус 429, але з різних причин — перевірте код помилки в тілі, щоб їх розрізнити.
- Похвилинний ліміт частоти — стеля сплеску, скидається щохвилини.
- Денна квота — ваші загальні виміряні виклики за день, скидається опівночі за UTC.
- Квота рахується один раз на акаунт, спільна для всіх ваших ключів.
2Денна квота за тарифом
Ваша денна квота — це кількість виміряних викликів API, які ви можете зробити за добу UTC, і вона залежить від тарифу. Лічильник спільний для всіх ваших ключів і слідує найкращому тарифу серед груп, які ви адмініструєте — без платної підписки ви на рівні Free.
Вікно — це календарна доба UTC, тож ваш лічильник використання скидається до нуля опівночі за UTC. Пакетна перевірка спаму коштує один виклик на елемент у пакеті, а не один виклик на весь запит.
- Free — 100 викликів на день.
- Basic — 1 000 викликів на день.
- Pro — 10 000 викликів на день.
- Business — 50 000 викликів на день.
3Похвилинний ліміт частоти за тарифом
На додачу до денної квоти кожен API-ключ обмежений кількістю запитів за хвилину відповідно до рівня його тарифу. Це згладжувальний ліміт: він не дає одному клієнту надіслати величезний сплеск за одну секунду, навіть коли денний бюджет далеко не витрачено.
Окремо широкі стелі на IP та на акаунт застосовуються по всьому API, щоб тримати платформу стабільною. У звичайному використанні — рівні, розмірені запити — ви ніколи їх не торкнетеся; вони спрацьовують лише на зловживальних сплесках.
- Free та Basic — 60 запитів за хвилину.
- Pro — 600 запитів за хвилину.
- Business — 1 800 запитів за хвилину.
- Розподіляйте запити, а не випалюйте їх усі за раз.
4Читання залишкового бюджету
Вам ніколи не доводиться вгадувати, скільки квоти лишилося. Кожна виміряна відповідь — успіх чи невдача — містить три заголовки: X-Quota-Limit (ваш денний ліміт), X-Quota-Used (скільки викликів ви витратили сьогодні) та X-Quota-Reset (момент за UTC, коли лічильник скидається).
Ендпоінти перевірки спаму також дублюють ті самі числа всередині тіла відповіді під об'єктом quota, тож ви можете читати свій залишковий бюджет без парсингу заголовків. Використовуйте їх, щоб розмірювати власні запити та попереджати себе, перш ніж закінчиться.
- X-Quota-Limit — ваш денний ліміт викликів.
- X-Quota-Used — витрачені виклики за сьогодні.
- X-Quota-Reset — час скидання за UTC (RFC 3339).
- Відповіді перевірки спаму також містять об'єкт quota з тими самими полями.
5Що відбувається при 429
Коли ви перетинаєте будь-який ліміт, API повертає HTTP 429 із заголовком Retry-After, що каже, скільки секунд чекати. Для похвилинного ліміту частоти Retry-After — близько хвилини. Для денної квоти тіло несе код daily_quota_exceeded плюс ваш тариф, ліміт, лічильник використання, час скидання та підказку про оновлення, а Retry-After відлічує до опівночі за UTC.
Правильний спосіб обробити 429 — відступити й повторити після затримки Retry-After, а не гатити ендпоінт. Добре поводжувані клієнти читають заголовок і паузять; клієнти, що продовжують повторювати одразу, просто лишаються заблокованими.
- 429 rate_limit_exceeded — ви надіслали надто швидко; зачекайте близько хвилини.
- 429 daily_quota_exceeded — день вичерпано; зачекайте до скидання за UTC або оновіть тариф.
- Завжди дотримуйтесь заголовка Retry-After перед повтором.