Лимиты и ограничения REST

REST API Битрикс24 защищён двумя независимыми ограничителями: лимитом частоты (сколько запросов в секунду) и операционным лимитом нагрузки (сколько «тяжести» метод создаёт за окно времени). Понимание обоих — обязательное условие устойчивой интеграции.

Лимит частоты запросов

Базовое ограничение — не более 2 запросов в секунду к порталу. Работает оно по принципу «дырявого ведра» (leaky bucket): у приложения есть ёмкость, которая пополняется во времени, а каждый запрос её расходует. Короткие всплески допустимы, но устойчивый поток выше двух запросов в секунду начнёт отклоняться.

При превышении сервер возвращает ошибку с кодом QUERY_LIMIT_EXCEEDED и сообщением о слишком частых обращениях. Запрос при этом не выполняется — его нужно повторить позже.

Операционный лимит нагрузки

Лимита частоты недостаточно: два «тяжёлых» запроса в секунду могут нагрузить портал сильнее, чем десяток лёгких. Поэтому введён второй ограничитель — операционный лимит (метод «интенсивности»). Каждый вызов расходует «операционное время», а ресурс восстанавливается в скользящем окне.

Суть модели:

• У каждого метода есть операционная «стоимость» — время, которое портал тратит на выполнение.
• Портал суммирует это время в скользящем окне (порядка 10 минут).
• При исчерпании лимита метод временно блокируется до восстановления ресурса.

При превышении возвращается ошибка OPERATION_TIME_LIMIT. В отличие от частотного лимита, здесь важна не скорость, а суммарная тяжесть запросов за окно.

Как отслеживать остаток лимита

Ответ REST содержит служебный блок time, а тяжёлые ограничители сопровождаются HTTP-заголовками семейства X-RateLimit. По ним можно строить адаптивную стратегию — притормаживать до восстановления, а не биться в стену.

Опираясь на operating_reset_at, можно рассчитать паузу до восстановления ресурса и не тратить попытки впустую.

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

Помимо двух главных ограничителей, стоит держать в голове ряд практических потолков:

• Размер страницы списка — фиксированные 50 записей, не настраивается.
• Команд в batch — не более 50 за вызов.
• Размер тела запроса — ограничен настройками веб-сервера портала; крупные файлы через base64 упираются в этот потолок.
• Тайм-аут выполнения — долгие методы могут прерываться по времени обработки.
• Число событий и обработчиков — регистрация обработчиков событий также лимитирована.

Отдельно учитывайте, что у коробочной версии (Битрикс24 On-Premise) часть лимитов настраивается администратором и агентами, а в облаке они заданы платформой и зависят от тарифа.

Стратегии, чтобы не упираться в лимиты

Устойчивая интеграция закладывает работу с лимитами в архитектуру, а не борется с ними постфактум:

1. Пакетируйте запросы через batch — до 50 операций за один сетевой запрос.
2. Выбирайте только нужные поля через select и сужайте filter — легче запрос, меньше операционное время.
3. Отключайте подсчёт total через start=-1 на массовых выгрузках.
4. Реализуйте backoff — при QUERY_LIMIT_EXCEEDED и OPERATION_TIME_LIMIT повторяйте с нарастающей паузой.
5. Выносите тяжёлые обмены в очередь и растягивайте их во времени, а не запускайте пиком.

Диагностика превышений

Когда интеграция начинает ловить блокировки, важно быстро понять, в какой именно лимит она упёрлась — частотный или операционный. Реакция на них разная.

• Симптом частотного лимита — ошибка QUERY_LIMIT_EXCEEDED на пике параллельных запросов, при этом отдельные методы работают быстро. Лечится дросселированием потока и пакетированием.
• Симптом операционного лимита — ошибка OPERATION_TIME_LIMIT после серии тяжёлых выборок, даже если запросов немного. Лечится облегчением методов и растягиванием во времени.

Полезно вести собственную метрику: логировать time.duration и time.operating каждого ответа. Так вы заранее увидите, какие методы «съедают» операционный ресурс, и оптимизируете именно их — например, уберёте лишние поля из select или разгрузите фильтр.

Итог

В REST Битрикс24 работают два ограничителя: частотный (2 запроса в секунду, ошибка QUERY_LIMIT_EXCEEDED) и операционный по нагрузке метода (ошибка OPERATION_TIME_LIMIT). Следите за блоком time и заголовками X-RateLimit, пакетируйте запросы через batch, отключайте подсчёт total и стройте разумный backoff.

Мы в B2Bsite проектируем высоконагруженные интеграции с Битрикс24, которые держат объём без штрафов по лимитам: очереди, пакетирование, событийная модель вместо опроса. Если ваш обмен ловит блокировки — поможем перестроить его на архитектуру, дружелюбную к лимитам.