Перейти к содержанию

Лимиты

Текущие лимиты

Эндпоинт Лимит Скоуп
POST /api/v1/verifications/ 120 req/min На один API-ключ (по prefix)
GET /api/v1/verifications/{id}/ 120 req/min На один API-ключ

Лимит считается за скользящее окно в одну минуту. То есть если вы сделали 120 запросов в 12:30:00, следующий запрос пройдёт только после 12:31:00 — равномерное распределение приветствуется.

Что происходит при превышении

HTTP 429 Too Many Requests:

{
  "detail": "Request was throttled. Expected available in 23 seconds."
}

В заголовках:

Retry-After: 23

Подождите указанное число секунд и повторите. Игнорировать Retry-After нельзя — каждая попытка до истечения окна снова получит 429 и в крайнем случае может привести к временной блокировке ключа.

Burst и стратегия клиента

  • Лимит не позволяет burst свыше 120 req за 60-секундное окно. Запрос на 121-й будет отклонён, даже если предыдущие 120 уложились в первые 10 секунд.
  • На клиенте — простой rate-limiter: token-bucket с ёмкостью 120 и пополнением 2 токена/сек (120/60).
  • Если ожидаете пиковые нагрузки выше лимита — напишите в саппорт, обсудим повышение для вашего ключа.

Идемпотентность и ретраи

Текущий POST /verifications/ не идемпотентен. Если вы ретраите из-за сетевой ошибки и при этом первая попытка на самом деле дошла — вы получите две разные верификации (две разные verification_id, два разных dial_number). Это:

  • Заберёт два DID вместо одного → быстрее упретесь в 503.
  • Запутает пользователя — какой из двух номеров набирать.

Стратегия:

  1. На сетевой таймаут — не ретраить сразу. Подождите 5–10 секунд и сделайте GET /verifications/{id}/ — но ID-то у вас нет.
  2. Проще: если ваш бэкенд видит таймаут на POST, отметьте у пользователя «попробуйте ещё раз через минуту» и не ретраите автоматически.
  3. Если запрос вернулся с HTTP-статусом (200/4xx/5xx) — это уже не таймаут, ретрай на месте оправдан только для 429/503.

Поддержка Idempotency-Key заголовка планируется — следите за обновлениями документации.

Прочие ограничения

  • Размер тела запроса — до 1 MB.
  • Размер webhook_url — до 500 символов.
  • Размер client_ref — до 120 символов.
  • Размер phone — до 32 символов (E.164).

При превышении — 400 Bad Request с конкретным сообщением.

Мониторинг лимита

В дашборде на странице Keys под каждым ключом показывается:

  • Использование за последние 24 часа (грубо).
  • Последние 429-ответы (если были).

Если регулярно упираетесь — пишите в саппорт. Скорее всего вам нужен выделенный лимит или альтернативная схема (например, batch-эндпоинт).

Дашборд-эндпоинты

Внутренние /api/dashboard/* имеют отдельные лимиты:

  • POST /api/dashboard/auth/login — 10 req/min на IP.
  • POST /api/dashboard/keys (создание ключа) — 10 req/hour на пользователя.

Эти эндпоинты не публичные и используются веб-дашбордом — клиентам API с ними работать не нужно.