Ограничение частоты и IP‑allowlist

​

Ограничение частоты (rate limit)

К API применяется ограничение частоты запросов.

Параметр	Значение
Бюджет	по умолчанию 120 запросов в минуту
На что считается	на IP‑адрес клиента (не на API‑ключ и не на мерчанта)
Окно	фиксированное окно в одну минуту (счётчик заводится на первом запросе и обнуляется через минуту)
При превышении	HTTP 429, заголовок Retry-After: 60, тело {"state":1,"message":"rate limit exceeded"}

Ключ — это IP. Лимит общий для всех запросов с одного IP: все запросы вашего backend делят один бюджет, и разносить операции по разным API‑ключам бесполезно. Точное значение в проде может отличаться от 120/мин по умолчанию, поэтому не «зашивайте» 120 в логику — ориентируйтесь на ответ 429 и заголовок Retry-After.

​

Что делать при 429

Обратите внимание: тело 429 — это {"state":1,"message":…}, не стандартный конверт {"error":{…}}. Правильная реакция:

1. Прочитайте Retry-After (секунды) и подождите это время, либо повторяйте с экспоненциальным backoff.
2. Повторите тот же запрос. Благодаря идемпотентности по order_id повтор денег‑движущих операций безопасен — дубля не возникнет.

Все SDK делают это автоматически: ловят 429, читают Retry-After и повторяют.

​

Как не упереться в лимит

• Не распараллеливайте сотнями. Держите разумную конкурентность (единицы–десятки одновременных запросов), а не «выстрел» из сотни.
• Кэшируйте редко меняющееся. Ответы /v1/payment/services, /v1/currencies, /v1/exchange-rate/list можно кэшировать на минуты — не запрашивайте их на каждый показ страницы.
• Не поллите статус. Не опрашивайте /v1/payment/info в цикле — статус вам сообщит вебхук. Опрос уместен только как редкий фолбэк.
• Массовые операции — батчами. Это штатный способ не упираться в лимит: батч из 5000 элементов — это один запрос в бюджете, а не 5000. Используйте /v1/payment/batch, /v1/refund/batch, /v1/payout/batch и опрашивайте результат через /v1/batch/info. Устаревший /v1/payout/mass (до 100, синхронный) годится только для маленьких пачек.

---

​

IP‑allowlist

Для вашего API‑ключа можно включить список доверенных IP‑адресов. Когда список включён, подписанные запросы с IP вне списка отклоняются с ошибкой 401 auth.ip_not_allowed.

По умолчанию allowlist выключен. В проде рекомендуется его включить и ограничить доступ IP‑адресами вашего backend.

Управление списком — отдельные методы:

Метод	Назначение
POST /v1/api-allowlist/list	Показать список и статус.
POST /v1/api-allowlist/add	Добавить IP или CIDR.
POST /v1/api-allowlist/remove	Удалить запись.
POST /v1/api-allowlist/enable	Включить/выключить контроль.

Полное описание — на странице IP‑allowlist.

---

​

Связанные страницы

Массовые операции: /v1/payment/batch

/v1/payout/batch

/v1/batch/info

IP‑allowlist — методы

Идемпотентность

Безопасность в проде