# Ограничения при работе с API

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

Mindbox ограничивает количество обращений к API в минуту. Если вы превысите лимит, API вернет `429 Too Many Requests` — такой запрос не будет обработан. Повторите его позже с экспоненциальной задержкой, а последующие запросы отправляйте с меньшей скоростью.

Каждый вызов проверяется сразу по двум лимитам:

* **лимит на одну операцию** — количество вызовов конкретной операции через конкретную точку интеграции;
* **лимит на весь проект** — суммарное количество вызовов операций одного типа по всему проекту.

`429` возвращается при превышении любого из двух.

### Что определяет лимит

Величина лимита зависит от характеристик вашей операции и размера клиентской базы.

* **Синхронная или асинхронная.** Синхронные операции возвращают результат в ответ на запрос. Асинхронные — принимают запрос и обрабатывают его в фоне, не блокируя ответ.
* **Чтение или запись** (только для синхронных). Операции, которые возвращают данные (например, профиль клиента или расчет заказа), и операции, которые создают или изменяют данные, учитываются отдельно.
* **Приоритетная или стандартная.** Приоритетные операции используются в сценариях реального времени: оформление заказа на кассе, проверка баланса бонусов, отправка кода авторизации. Стандартные — для фоновых задач и неприоритетных операций: просмотр продукта, изменение статуса заказа в системе и других. Приоритет операции выбирается при ее [настройке в Mindbox](https://help.mindbox.ru/docs/%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D0%B8-v-%D0%BE%D1%81%D0%BD%D0%BE%D0%B2%D0%BD%D1%8B%D0%B5-%D1%81%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D1%8F).
* **Размер базы клиентов.** Лимит зависит от количества клиентов на проекте и масштабируется автоматически по мере роста проекта.

### Лимиты (запросов в минуту)

| Тип операции | Лимит | до 1 млн клиентов | 1–⁠5 млн | 5–⁠20 млн | более 20 млн |
| :--- | :--- | ---: | ---: | ---: | ---: |
| **Синхронная, чтение, приоритетная** | на операцию | 2 000 | 3 000 | 4 000 | 10 000 |
| | на проект | 3 000 | 4 000 | 5 000 | 15 000 |
| **Синхронная, запись, приоритетная** | на операцию | 1 000 | 1 500 | 2 000 | 3 000 |
| | на проект | 1 500 | 3 000 | 3 000 | 3 500 |
| **Синхронная, чтение, стандартная** | на операцию | 3 000 | 4 000 | 5 000 | 6 000 |
| | на проект | 6 000 | 7 000 | 10 000 | 12 000 |
| **Синхронная, запись, стандартная** | на операцию | 3 500 | 4 000 | 5 000 | 6 000 |
| | на проект | 6 000 | 7 000 | 10 000 | 12 000 |
| **Асинхронная, приоритетная** | на операцию | 600 | 800 | 1 000 | 1 500 |
| | на проект | 800 | 1 500 | 2 000 | 5 600 |
| **Асинхронная, стандартная** | на операцию | 5 000 | 7 000 | 10 000 | 12 000 |
| | на проект | 13 000 | 20 000 | 26 000 | 35 000 |

## Одновременные запросы к одному клиенту

Если два синхронных запроса на изменение одного и того же клиента поступают одновременно, второй запрос может получить `429 Too Many Requests` с сообщением `Too many concurrent operations for the same contact`.

**Как это работает.** Когда синхронная операция записи начинает обрабатываться, Mindbox временно блокирует контакт по его идентификаторам (email, телефон и другим). Если в этот момент поступает другой запрос, затрагивающий тот же контакт, Mindbox повторяет обработку конфликтующего запроса несколько раз. Если к моменту повтора первая операция завершилась и блокировка снята, повторный запрос выполнится успешно. Если блокировка так и не снялась — возвращается `429`. Блокировка снимается сразу после завершения первой операции или автоматически через 5 секунд.

**На что распространяется.** Только на синхронные операции записи. Операции чтения и асинхронные операции этим ограничением не затрагиваются.

**Что делать.** Не отправляйте параллельные запросы на изменение одного клиента. При получении `429` с этим сообщением подождите немного и повторите запрос — к тому моменту первая операция, как правило, уже завершится.

## Ограничение для расчета заказов с большим объемом

На проекте не должно быть более 10% запросов «Предварительный расчет заказа» с более чем 50 строками в течение 2 минут. Первый такой запрос за 2 минуты не учитывается в квоте: подсчет начинается со второго запроса.

При нарушении API возвращает `429 Too Many Requests` с сообщением:

```text
Only 10% of calculations for orders with over 50 lines per 2 minute(s) are allowed.
```

Повторите запрос через 2 минуты при необходимости.

## Ограничение на количество импортов

Каждый метод импорта позволяет поставить не более 60 импортов в час. После превышения лимита API возвращает `429 Too Many Requests`, пока количество поставленных за час импортов не опустится ниже 60.

Ограничения на размер файлов и формат данных при импорте описаны в статье [Ограничения при импорте данных](/docs/data-import-limitations).
