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 — 1000 вызовов в день.
- Pro — 10 000 вызовов в день.
- Business — 50 000 вызовов в день.
3Поминутный лимит частоты по тарифу
Помимо суточной квоты, каждый ключ API ограничен числом запросов в минуту в соответствии с уровнем его тарифа. Это сглаживающий лимит: он не даёт одному клиенту отправить огромный всплеск за одну секунду, даже когда суточный бюджет далёк от исчерпания.
Отдельно широкие потолки на IP и на аккаунт применяются по всему API, чтобы держать платформу стабильной. При обычном использовании — ровные, размеренные запросы — вы никогда их не коснётесь; они срабатывают только на злоупотребляющих всплесках.
- Free и Basic — 60 запросов в минуту.
- Pro — 600 запросов в минуту.
- Business — 1800 запросов в минуту.
- Распределяйте запросы, а не выпускайте их все сразу.
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 перед повтором.