Лимиты REST API

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

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

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

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

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

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

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

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

Ограничение времени SQL-запросаОграничение времени SQL-запроса

Битрикс24 ограничивает время выполнения одного SQL-запроса внутри REST-метода. Ограничение действует для классических методов и методов REST 3.0. В облачной версии значение лимита задается конфигурацией Битрикс24. В коробочной версии ограничение по умолчанию выключено. Администратор включает его в настройках модуля rest и задает лимит в секундах, по умолчанию 30 секунд. Настройка доступна, только если ее поддерживает база данных.

Если SQL-запрос не уложился в лимит, метод вернет ошибку BITRIX_REST_V3_EXCEPTION_LIMITER_QUERYTIMELIMITEXCEPTION с текстом «Запрос отменён из-за превышения лимита времени» и HTTP-статусом 503. В заголовке Retry-After приходит лимит в секундах. Классические методы на контроллерах Engine возвращают HTTP-статус 400 без Retry-After. В batch ошибка приходит в результате того подзапроса, который превысил лимит.

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

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

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

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

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

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

Значения X и Y зависят от тарифа.

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

Чтобы оценить, сколько запросов можно выполнить, считайте по минимальной устойчивой интенсивности — 2 запроса в секунду. Это 172 800 запросов в сутки. Кратковременно интенсивность может быть выше.

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

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

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

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

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

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

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

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

Фрагмент ответа — объект time:

{
    "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 входят текущая минута и девять предыдущих.

Корзина выходит из расчета, когда начинается десятая минута после нее. Ключ operating_reset_at — время в формате timestamp, когда Битрикс24 удаляет самую старую корзину: через 10 минут после первого учтенного в ней вызова. Например, если первый вызов в корзине 10:05 начался в 10:05:20, корзина перестанет учитываться в 10:15:00, а operating_reset_at будет соответствовать 10:15:20. После operating_reset_at эта корзина точно не учитывается.

При этом operating не обязательно обнуляется: корзины следующих минут остаются в расчете.

Битрикс24 проверяет накопленное время перед каждым вызовом. Вызов, на котором время превысило лимит, выполняется до конца. Следующий вызов блокируется с ошибкой OPERATION_TIME_LIMIT, и метод остается заблокированным 5 минут, даже если за это время из расчета вышли старые корзины. После блокировки накопленное время метода считается с нуля.

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

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

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

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

• load_limiter_active — включение
• load_limiter_second_limit — лимит в секундах
• load_limiter_connection_name — соединение с Redis

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

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

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

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