> ## Documentation Index
> Fetch the complete documentation index at: https://oblodai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

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

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

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

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

Все [SDK](/sdk/overview) делают это автоматически: ловят 429, читают `Retry-After` и повторяют.

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

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

***

## IP‑allowlist

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

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

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

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

Полное описание — на странице [IP‑allowlist](/reference/api-allowlist).

***

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

<CardGroup cols={2}>
  <Card title="Массовые операции: /v1/payment/batch" href="/reference/payment-batch" icon="arrow-right" horizontal />

  <Card title="/v1/payout/batch" href="/reference/payout-batch" icon="arrow-right" horizontal />

  <Card title="/v1/batch/info" href="/reference/batch-info" icon="arrow-right" horizontal />

  <Card title="IP‑allowlist — методы" href="/reference/api-allowlist" icon="arrow-right" horizontal />

  <Card title="Идемпотентность" href="/reference/basics-idempotency" icon="arrow-right" horizontal />

  <Card title="Безопасность в проде" href="/guides/production-security" icon="arrow-right" horizontal />
</CardGroup>