Ограничения частоты запросов

Ограничение частоты запросов определяет максимальное количество запросов, которое приложение может отправить к API в течение заданного периода времени. Этот механизм необходим для поддержания общей работоспособности и надёжности сервисов.

Зачем используется ограничение частоты запросов

API stability and performance

• Предотвращает перегрузку серверов чрезмерными запросами от одного клиента.
• Обеспечивает стабильное и предсказуемое время отклика для всех клиентов.
• Защищает бэкенд-сервисы от неожиданных всплесков трафика.
• Поддерживает стабильную и управляемую нагрузку на инфраструктуру.

Security

• Усиливает защиту от атак, таких как перебор паролей.
• Снижает риск распределённых атак типа «отказ в обслуживании» (DDoS).
• Уменьшает влияние плохо реализованных интеграций.
• Ограничивает потенциальный ущерб от компрометации учётных данных API.

Resource allocation

• Обеспечивает сбалансированный доступ к ресурсам API для всех клиентов.
• Предотвращает деградацию опыта других пользователей из-за злоупотреблений.
• Позволяет приоритизировать трафик согласно бизнес-критериям и потребностям.
• Стимулирует более эффективное и устойчивое использование API.

Как работает ограничение частоты запросов

Каждый вызов API учитывается в счёт допустимого лимита запросов в секунду. Значение по умолчанию — 10 RPS на тенант. При превышении лимита API возвращает HTTP 429 Too Many Requests.

Уточните у вашей команды по подключению

Точные лимиты настраиваются для каждого тенанта индивидуально. Обратитесь к вашей команде по подключению, чтобы уточнить лимиты для вашего аккаунта перед планированием высоконагруженных интеграций.

Обработка ошибок 429

Request a rate limit increase

Если ожидается рост объёма запросов (временный или постоянный), уведомите команду Unico об увеличении лимита для вашей среды. Этот запрос необходимо сделать до фактического роста нагрузки, чтобы избежать нарушений в работе приложения.

Review application behavior

• Проверьте код на наличие неэффективных паттернов использования API.
• Найдите непреднамеренные циклы или избыточные вызовы API.
• Распределяйте запросы равномернее во времени вместо отправки крупными пакетами.

Implement caching

• Кэшируйте часто запрашиваемые данные, которые редко изменяются.
• Используйте токен доступа OAuth2 в течение всего его TTL (1 час) — не вызывайте POST /oauth2/token при каждом запросе.
• Реализуйте подходящие стратегии инвалидации кэша.

Use webhooks instead of polling

Подпишитесь на Webhooks и события для PROCESS_STATE_FINISHED вместо опроса GET /client/v1/process/\{id\}. Цикл polling может легко исчерпать бюджет GET-process при интенсивном трафике.

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

Платформа возвращает:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Заголовок	Значение
Retry-After	Количество секунд ожидания перед повторной попыткой. Соблюдайте его.

Если Retry-After отсутствует, используйте экспоненциальную задержку (1 с, 2 с, 4 с, 8 с, …) с ограничением 60 с.

Соображения о параллелизме

Ограничения частоты запросов ограничивают запросы в минуту, но платформа также имеет ограничения параллелизма на уровне инфраструктуры. Даже если у вас есть бюджет на 100 запросов/минуту, отправка всех 100 в одну секунду с большей вероятностью приведёт к отказу, чем равномерное распределение по минуте.

Для высоконагруженных интеграций стремитесь к стабильному RPS, а не к пиковым нагрузкам.

Доставка webhook Magic Link

Trully имеет собственные квоты доставки для Webhook V2. Ожидается, что webhook-сервер ответит в течение 1 минуты; более медленные ответы отбрасываются (процесс пользователя при этом не затрагивается). Для надёжной обработки подтверждайте webhook быстро и обрабатывайте его асинхронно.

Что дальше

• Аутентификация — стратегия кэширования токенов.
• Webhooks и события — замена polling на push.
• Коды ошибок > Политика повторных попыток — когда (и когда не) повторять попытки.