У REST API Битрикс24 четыре ограничения, которые нужно заложить в проект интеграции до первой строки кода: частота запросов (на большинстве тарифов счётчик убывает на 2 запроса в секунду, блокировка после 50), суммарное время работы каждого метода за 10 минут, 60 секунд на один запрос и 50 записей на страницу в списочных методах. Если их не учесть, интеграция работает на тесте и ломается на живых данных.
Типичная картина выглядит так. Подрядчик пишет обмен сайта или учётной системы с CRM, проверяет его на сотне тестовых сделок, всё летает. Через месяц в портале уже сорок тысяч контактов, ночная синхронизация начинает падать с непонятными ошибками, а менеджеры утром видят в карточках вчерашние остатки и цены. Код при этом никто не трогал. Просто объём данных дорос до лимитов, о которых при разработке никто не подумал.
Что такое REST API Битрикс24 и почему у него есть лимиты
REST API Битрикс24 — это программный интерфейс, через который внешние системы читают и меняют данные портала: сделки, контакты, задачи, товары, файлы. Через него работают интеграции с сайтом, 1С, телефонией, рекламными кабинетами и все приложения из Маркета.
Облачный портал живёт на общей инфраструктуре. Если одна интеграция начнёт отправлять тысячи запросов в секунду, она замедлит работу портала для всех сотрудников, которые в это время открывают карточки и двигают сделки. Поэтому платформа ограничивает и количество запросов, и то, сколько времени сервер тратит на их выполнение. Для бизнеса это означает простую вещь: скорость любого обмена данными с Битрикс24 имеет потолок, и его нельзя поднять, купив сервер помощнее на своей стороне.
Все цифры ниже взяты из официальной документации Битрикс24 об ограничениях REST API. Платформа периодически меняет правила, поэтому перед стартом крупного проекта мы всегда перечитываем этот раздел заново.
Сколько запросов в секунду можно отправлять в Битрикс24
Средняя допустимая скорость на большинстве тарифов составляет 2 запроса в секунду, на тарифе Энтерпрайз 5 запросов в секунду. Короткие всплески допускаются: блокировка наступает, когда счётчик запросов превысит 50 (на Энтерпрайзе 250).
Работает это по алгоритму «дырявого ведра» (leaky bucket). Каждый запрос добавляет в счётчик единицу, а счётчик постоянно уменьшается с фиксированной скоростью. Пока значение ниже порога, запросы проходят. Как только порог превышен, портал отвечает ошибкой QUERY_LIMIT_EXCEEDED с HTTP-статусом 503 и не выполняет запрос, пока счётчик снова не опустится.
| Параметр | Энтерпрайз | Остальные тарифы |
|---|---|---|
| Скорость уменьшения счётчика | 5 в секунду | 2 в секунду |
| Порог блокировки | 250 | 50 |
| Ошибка при превышении | QUERY_LIMIT_EXCEEDED, HTTP 503 | |
На практике это значит, что интеграция может быстро отправить пачку из нескольких десятков запросов, но дальше должна держать темп. Выгрузка десяти тысяч карточек по одной за запрос при скорости 2 в секунду займёт больше часа. Если разработчик об этом не знает, он пишет цикл без пауз, первые 50 запросов проходят мгновенно, а остальные сыплются ошибками.
Отсюда первое требование к любому техническому заданию на интеграцию: код обязан обрабатывать ответ 503, делать паузу и повторять запрос. Без этого обмен теряет данные молча, и об этом узнают по жалобам менеджеров, а не по логам.
Что такое лимит на время выполнения методов
Лимит на время выполнения (operating) — это ограничение на суммарное время, которое сервер тратит на один и тот же метод REST API за скользящие 10 минут. Он считается отдельно для каждого метода и отдельно для каждого приложения или вебхука.
Он ловит другой тип нагрузки. Можно отправлять запросы медленно и аккуратно, но если каждый из них тяжёлый (например, выборка сделок со сложным фильтром по большой базе), сервер всё равно тратит много времени. Битрикс24 складывает время выполнения метода в 10 минутных «корзин». Когда сумма превышает лимит, следующий вызов этого метода блокируется ошибкой OPERATION_TIME_LIMIT с HTTP-статусом 429. Разблокировка происходит, когда самая старая корзина выпадает из расчёта и сумма опускается ниже порога.
Для коробочной версии документация называет значение по умолчанию: 420 секунд за 10 минут. Для облака конкретную цифру мы здесь не приводим, её лучше смотреть в ответах самого портала. В каждом ответе API есть блок time, в нём поле operating показывает накопленное время по методу, а operating_reset_at говорит, когда из расчёта выпадет самая старая корзина. Грамотная интеграция читает эти поля и сама снижает темп до того, как упрётся в блокировку.
Важная деталь для планирования: лимит привязан к методу. Если интеграция упёрлась в лимит на выборку сделок, запросы к контактам или задачам продолжат работать. Поэтому зависшая выгрузка сделок не обязательно ломает всё остальное, и это стоит учитывать при разборе инцидентов.
Почему запрос обрывается через 60 секунд
Один REST-запрос к Битрикс24 должен выполниться не дольше 60 секунд. Если сервер не успевает, запрос прерывается, и интеграция получает ошибку вместо данных.
Обычно в этот предел упираются две категории задач. Первая: выборки по огромным спискам с тяжёлыми фильтрами и подсчётом общего количества записей. Вторая: пакетные запросы, в которые положили максимум тяжёлых операций. Решение в обоих случаях одно: дробить работу на части и не просить сервер сделать за раз то, что можно сделать за десять спокойных шагов.
Как выгрузить из Битрикс24 больше 50 записей
Списочные методы вроде выборки сделок или контактов по умолчанию возвращают страницу из 50 записей. Чтобы забрать всё, нужно делать последовательные запросы, и от того, как именно их делать, зависит, займёт выгрузка минуты или часы.
Наивный способ, который встречается в половине самописных интеграций: сдвигать параметр start на 50 в каждом запросе. На небольшой базе это работает. На большой каждый такой запрос заставляет сервер заново считать общее количество записей, и выгрузка деградирует по мере роста базы.
Битрикс24 в рекомендациях по выгрузке больших объёмов данных предлагает другой порядок:
- Отсортировать выборку по ID по возрастанию.
- Добавить в фильтр условие
>IDс последним полученным идентификатором. - Передать
start = -1, чтобы отключить подсчёт общего количества. - После каждого ответа запоминать ID последней записи.
- Повторять, пока ответ не вернёт меньше 50 элементов.
Разница получается огромной. В той же документации приведён замер: на 2 387 743 элементах время выполнения запроса сократилось с 49,9 секунды до 0,097 секунды. Первое значение, кстати, опасно близко к пределу в 60 секунд, о котором шла речь выше. Там же есть две оговорки: между запросами всё равно нужны паузы, чтобы не упереться в лимит частоты, а состав данных может измениться прямо во время выгрузки, если кто-то удалит записи или поменяет права.
Сколько команд помещается в один batch-запрос
Пакетный запрос batch позволяет передать до 50 вызовов методов в одном HTTP-запросе. Это главный инструмент, чтобы уложиться в лимит частоты: вместо пятидесяти обращений к порталу интеграция делает одно.
Batch хорош для однотипных операций: обновить остатки по полусотне товаров, получить данные по списку контактов, создать пачку задач. Но пакет остаётся одним HTTP-запросом, поэтому тяжёлые выборки внутри него повышают риск упереться в предел по времени. Время работы методов внутри пакета тоже никуда не исчезает, поэтому batch не отменяет необходимость следить за полем operating.
В сентябре 2026 года Битрикс24 описал в документации batch для REST 3.0 с передачей результата одного подзапроса в параметры следующего. Подробности и то, что это меняет для бизнеса, мы разбирали в отдельном материале про batch 3.0 и методы BI-Конструктора. Общие правила пакетных вызовов описаны в разделе документации о методе batch.
Чем вебхук отличается от приложения и где у него потолок
Входящий вебхук — это секретный адрес, по которому внешняя система вызывает методы REST API от имени сотрудника, создавшего вебхук. Это самый быстрый способ подключить интеграцию к одному порталу, и большинство заказных обменов с сайтами и учётными системами построено именно на нём.
Но у вебхука три ограничения, которые важно знать до выбора архитектуры. Они описаны в справке Битрикс24 о локальных вебхуках.
- Запросы выполняются в рамках разделов (scope), выбранных в настройках вебхука, и с правами сотрудника, который его создал. Если этот сотрудник видит только свои сделки, интеграция тоже увидит только их. Если учётную запись сотрудника отключат после увольнения, обмен может остановиться.
- Часть методов требует контекста приложения. Документация называет примеры: встраивание виджетов в интерфейс через
placement.bind, часть методов телефонии и некоторые сценарии чат-ботов. - Вебхук не подходит, если интеграцию нужно ставить на разные порталы, нужен собственный интерфейс внутри Битрикс24 или централизованная авторизация без передачи секретных адресов. Для этого делают локальное приложение или используют OAuth 2.0.
Для исходящих вебхуков, через которые Битрикс24 отправляет события во внешний обработчик, документация отдельно советует проверять подлинность запроса: сравнивать пришедший auth[application_token] с сохранённым значением. Без этой проверки любой, кто узнал адрес обработчика, может отправить в него поддельное событие.
На проектах B2BPRO.KZ мы чаще всего видим одну и ту же ошибку: вебхук создан под личной учётной записью руководителя или администратора, который потом уходит из компании. Мы рекомендуем заводить для интеграций отдельного технического пользователя с понятными правами и документировать, какие вебхуки от его имени работают.
Как настроить повтор запросов и не получить дубли
Повтор запроса после ошибки лимита обязателен, но он же порождает вторую проблему: дубли. Интеграция отправила команду на создание сделки, ответ не дошёл из-за таймаута, скрипт повторил попытку, и в CRM легли две одинаковые записи. Для чтения данных повтор безопасен, для создания записей нет.
Правило, которого мы придерживаемся в своих интеграциях, простое. Ошибки лимитов (503 и 429) повторяются всегда, но с растущей паузой: сначала секунда, потом две, потом четыре. Ошибки таймаута при создании записей повторяются только после проверки, не создалась ли запись в первый раз. Для этого в карточку сделки или контакта пишется внешний идентификатор из источника, например номер заявки на сайте или номер документа в учётной системе, и перед повтором интеграция ищет запись с таким идентификатором.
В REST 3.0 у Битрикс24 появился штатный механизм для этой задачи: заголовок Idempotency-Key. Если запрос с таким ключом уже отработал успешно, портал не создаёт вторую сущность и возвращает сохранённый ответ. Ключ должен быть привязан к смыслу операции, а не к попытке: если генерировать новый ключ на каждый повтор, защита не сработает. На новую версию API переведены пока не все методы, так что для части сценариев поиск по внешнему идентификатору остаётся единственным вариантом.
Ещё одна мера, которая окупается с первого инцидента, это журнал обмена. В нём должны оставаться время запроса, метод, код ответа и идентификатор записи. Когда менеджер приходит с вопросом, почему сделка не появилась, ответ находится за пару минут, без расследования по памяти.
Как ограничения REST API влияют на сроки и бюджет интеграции
Лимиты превращаются в деньги в тот момент, когда их обнаруживают после запуска. Переделать готовую интеграцию под пагинацию по ID, повторы запросов и контроль времени выполнения обходится дороже, чем заложить всё это в архитектуру сразу.
Вот как выглядит разница на примере. Этот пример иллюстративный, цифры округлены для наглядности. Компания в Алматы торгует оборудованием, у неё 30 тысяч товарных позиций в учётной системе, и остатки нужно обновлять в Битрикс24 каждую ночь.
| Подход | Как устроен обмен | Что происходит на живых данных |
|---|---|---|
| Без учёта лимитов | По одному запросу на товар, цикл без пауз | 30 тысяч запросов при скорости 2 в секунду требуют больше 4 часов, первые же всплески упираются в блокировку, часть обновлений теряется |
| С учётом лимитов | Пакеты по 50 команд, передаются только изменившиеся позиции, обработка 503 и 429 с повтором | Число HTTP-запросов сокращается в десятки раз, сбойные пакеты повторяются, в журнале видно, что и когда не прошло |
Второй подход дороже в разработке на несколько дней работы программиста. Первый дешевле на старте, но потом компания платит за ручные сверки, за ошибки менеджеров, которые продают отсутствующий товар, и за переделку. Если вы планируете крупную интеграцию и хотите заранее оценить нагрузку на портал, мы можем помочь в рамках услуги внедрение и настройка Битрикс24: разберём объёмы данных, выберем между вебхуком и приложением и заложим лимиты в техническое задание.
Что проверить в техническом задании до старта разработки
Перед тем как отдавать интеграцию подрядчику, стоит убедиться, что в ТЗ или в ответах исполнителя есть ответы на восемь вопросов. Этот список мы используем сами, когда принимаем чужие интеграции на сопровождение.
- Какой объём данных пойдёт через API сейчас и через год: сколько сделок, контактов, товаров, как часто они меняются.
- Как интеграция обрабатывает ошибку
QUERY_LIMIT_EXCEEDED(HTTP 503): есть ли пауза и повтор. - Как обрабатывается
OPERATION_TIME_LIMIT(HTTP 429) и читает ли код поляoperatingиoperating_reset_at. - Как выгружаются большие списки: через
startс шагом 50 или через фильтр по ID иstart = -1. - Используется ли batch для массовых однотипных операций и сколько тяжёлых команд кладётся в один пакет.
- От имени какого пользователя работает вебхук или приложение и что будет, если этот сотрудник уйдёт.
- Проверяет ли обработчик исходящих событий
application_token. - Где хранится журнал обмена и кто получает уведомление, если синхронизация не прошла.
Если на половину вопросов исполнитель отвечает «разберёмся по ходу», это повод остановиться. Лимиты REST API не относятся к экзотике: в них рано или поздно упирается любая интеграция, у которой растёт база.
Как понять, что интеграция уже упирается в лимиты
Самый надёжный признак: в журнале обмена появляются ошибки QUERY_LIMIT_EXCEEDED или OPERATION_TIME_LIMIT. Если журнала нет, признаки косвенные, и их обычно замечают менеджеры раньше, чем IT.
- ночная синхронизация заканчивается всё позже и позже, хотя код не менялся;
- часть сделок или товаров не обновилась, а остальные в порядке;
- обмен работает в выходные и ломается в будни, когда сотрудники тоже активно работают в портале;
- после подключения ещё одного сервиса начал сбоить старый.
Последний пункт проверяйте первым. Лимит на время выполнения считается отдельно для каждого приложения или вебхука, и если новый сервис подключили через тот же вебхук, что и старый, они делят один лимит на двоих. Отдельный вебхук под каждую интеграцию и свой журнал у каждой помогают найти виновника за минуты.
Частые вопросы
Сколько запросов в секунду выдерживает REST API Битрикс24?
На большинстве тарифов средняя скорость составляет 2 запроса в секунду, на тарифе Энтерпрайз 5 запросов в секунду. Короткие всплески допускаются: портал блокирует запросы, когда счётчик превысит 50 (на Энтерпрайзе 250), и отвечает ошибкой QUERY_LIMIT_EXCEEDED со статусом 503, пока счётчик не уменьшится.
Что значит ошибка OPERATION_TIME_LIMIT в Битрикс24?
Ошибка OPERATION_TIME_LIMIT означает, что метод REST API за последние 10 минут суммарно работал дольше допустимого для вашего приложения или вебхука. Портал возвращает статус 429 и не выполняет вызов этого метода, пока из расчёта не выпадет самая старая минутная корзина. Другие методы при этом продолжают работать.
Можно ли выгрузить все сделки из Битрикс24 одним запросом?
Нет, списочные методы по умолчанию отдают по 50 записей за запрос. Для больших объёмов Битрикс24 рекомендует сортировать по ID, фильтровать по условию больше последнего полученного ID и передавать start = -1, чтобы отключить подсчёт общего количества. Между запросами нужны паузы, чтобы не превысить лимит частоты.
Что лучше для интеграции с Битрикс24: вебхук или приложение?
Вебхук подходит для интеграции с одним порталом, когда достаточно прав одного сотрудника и не нужен интерфейс внутри Битрикс24. Приложение нужно, если интеграцию ставят на разные порталы, требуется встраивание виджетов, часть методов телефонии или чат-ботов, а также централизованная авторизация без передачи секретных адресов.
Можно ли увеличить лимиты REST API в облачном Битрикс24?
По документации лимит на частоту запросов выше на тарифе Энтерпрайз: 5 запросов в секунду вместо 2 и порог 250 вместо 50. На остальных тарифах скорость обмена увеличивают архитектурой: пакетными запросами batch, выгрузкой только изменившихся данных и пагинацией по ID вместо сдвига start.