Лимиты REST API

Лимиты интенсивности и ресурсоемкости REST-запросов действуют в облачной версии Битрикс24. В коробочной версии нагрузку настраивают на стороне сервера.

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

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

В облачной версии Битрикс24 один REST-запрос должен выполниться не дольше чем за 60 секунд. Если обработка занимает больше времени, запрос прерывается по таймауту.

На длительность запроса могут влиять объем данных, сложность фильтров, вложенные вызовы в batch и автоматизация, которая запускается при выполнении метода.

Чтобы снизить риск таймаута:

• разбивайте большие операции на несколько запросов
• используйте постраничную выборку и не запрашивайте лишние поля
• выносите долгие сценарии во внешнюю очередь или фоновую обработку на стороне приложения
• проверяйте поле duration в объекте time ответа

В коробочной версии Битрикс24 время выполнения запроса зависит от настроек сервера.

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

Лимит интенсивности запросов к Битрикс24 работает по принципу Leaky Bucket Algorithm. Приложение может кратковременно выполнять интенсивные запросы, но не может поддерживать такую интенсивность постоянно.

Механизм работает так:

1. Каждый запрос приложения увеличивает условный счетчик запросов в Битрикс24
2. Когда значение счетчика превышает порог X, следующий запрос блокируется со статусом 503 и кодом ошибки QUERY_LIMIT_EXCEEDED
3. Значение счетчика автоматически уменьшается на Y раз в секунду

Из этого следуют два правила:

1. При интенсивности не более Y запросов в секунду приложение не получит ошибку QUERY_LIMIT_EXCEEDED
2. Приложение может кратковременно выполнять больше Y запросов в секунду, например при одновременном поступлении нескольких звонков в интеграции с телефонией. Постоянно поддерживать такую интенсивность нельзя

Пороговые значения X и Y, о которых шла речь выше, зависят от тарифного плана.

Выполнение большого числа запросовВыполнение большого числа запросов

Чтобы оценить допустимый объем запросов, используйте минимальную устойчивую интенсивность как базовый расчет. При интенсивности 2 запроса в секунду за сутки можно выполнить 172 800 запросов. Механизм лимитов допускает кратковременное увеличение интенсивности сверх этого значения.

Лимит интенсивности учитывает HTTP-запросы, а не количество записей в ответе. Поэтому для получения данных можно использовать списочные методы *.list. Для многих таких методов размер страницы по умолчанию составляет 50 записей. Например, с интенсивностью 2 запроса в секунду при размере страницы 50 записей за сутки можно получить 8 640 000 записей.

Если нужно получать большие объемы данных через списочные методы REST API, применяйте рекомендации по выборке больших объемов. Они описывают постраничную выборку без подсчета общего количества элементов.

Чтобы сократить число HTTP-запросов, используйте метод batch. Он позволяет передать до 50 вызовов методов в одном HTTP-запросе.

Если batch последовательно выполняет 50 вызовов списочных методов и каждый вызов возвращает 50 записей, один HTTP-запрос вернет до 2500 записей. При интенсивности 2 HTTP-запроса в секунду расчетный верхний сценарий за сутки составит 432 000 000 записей. Это математический пример, а не гарантированный объем выгрузки: на практике результат зависит от ресурсоемкости методов, объема данных и активности в Битрикс24.

batch сокращает число HTTP-запросов, но не отменяет ограничение ресурсоемкости выполняемых методов. REST API не предназначен для массового и интенсивного обмена большими данными. Поэтому для встроенного BI-коннектора, который предназначен для получения больших данных, в Битрикс24 используется другой механизм.

Выбирайте подход по задаче:

Ограничения на ресурсоемкостьОграничения на ресурсоемкость

В облачной версии Битрикс24 массив time в ответе содержит ключ operating. Он показывает накопленное время выполнения конкретного метода отдельно для приложения или вебхука.

Пример ответа:

{
            ...
            "time": {
                "start": 1778747192.910734,
                "finish": 1778747193.530359,
                "duration": 0.6196250915527344,
                "processing": 0.032338857650756836,
                "date_start": "2026-05-14T10:26:32+02:00",
                "date_finish": "2026-05-14T10:26:33+02:00",
                "operating_reset_at": 1778747792,
                "operating": 3.3076241016387939
            }
        }
        

Время выполнения метода учитывается в 10 одноминутных корзинах. Каждая корзина хранит сумму времени выполнения метода за соответствующую минуту.

Ключ operating_reset_at содержит время в формате timestamp, когда из расчета исключается самая старая минутная корзина. Отсчет для корзины начинается с первого учтенного вызова метода в соответствующую минуту и длится 10 минут. Например, если первый вызов в корзине начался в 10:05:20 14 мая 2026 года, значение operating_reset_at будет соответствовать 10:15:20 14 мая 2026 года.

Когда наступает время из operating_reset_at, из operating исключается сумма времени в самой старой корзине. Значение может уменьшиться не до нуля: корзины следующих минут продолжают учитываться до собственного времени сброса.

Битрикс24 проверяет накопленное значение перед выполнением каждого вызова. Вызов, после которого значение превысило лимит, завершается. Следующий вызов блокируется с ошибкой OPERATION_TIME_LIMIT. Он снова станет доступен, когда после сброса одной или нескольких корзин значение operating перестанет превышать лимит.

Как реагировать на ошибки лимитовКак реагировать на ошибки лимитов

Внешний вызов batch не учитывается в operating. Вложенные вызовы выполняются как отдельные методы, поэтому время каждого из них учитывается и проверяется по его собственному лимиту.

Для примера предположим, что установленный лимит равен 480 секундам. Приложение вызывает метод crm.item.list, каждый вызов выполняется 20 секунд:

• за 10 минут приложение выполнило 20 вызовов, поэтому operating равен 400 секундам
• затем завершились еще пять вызовов, и operating достиг 500 секунд
• следующий вызов будет заблокирован, так как перед его выполнением значение уже превышает 480 секунд
• когда самая старая корзина, в которой накоплено 40 секунд, выйдет из расчета, operating уменьшится до 460 секунд и вызовы снова станут доступны

Значение лимита в облачной версии задается конфигурацией Битрикс24. В коробочной версии ограничение по умолчанию выключено. Если его включить, лимит по умолчанию составит 420 секунд. Администратор может изменить это значение в настройках модуля rest.

Показатели рассчитываются внутри Битрикс24. На них влияют объем данных, активность пользователей и других приложений.

Один и тот же запрос в разных Битрикс24 может вернуть разные значения operating. Например, для получения результата в одном Битрикс24 потребуется обработать 10 записей, а в другом — 10 000. Ресурсоемкость запроса нельзя определить только на стороне приложения.

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