Мы часто сталкиваемся с ситуацией: интеграция работает, данные синхронизируются — а потом в пятницу вечером скрипт начинает слать запросы в цикле без пауз, упирается в лимит, получает ошибку QUERY_LIMIT_EXCEEDED и падает. Или хуже — не падает, а повторяет запрос немедленно, усугубляя ситуацию. API Битрикс24 имеет жёсткие rate limits, и любая интеграция обязана их учитывать. Иначе — потеря данных, рассинхронизация, блокировка приложения. Наш опыт показывает: правильная настройка rate-limiting экономит часы отладки и предотвращает инциденты. Наша команда имеет 10+ лет опыта разработки на Битрикс24 и реализовала более 50 интеграций, поэтому мы знаем все подводные камни. В этой статье мы разберём лимиты REST API Битрикс24, методы оптимизации и конкретные сценарии, которые мы реализуем для клиентов. Вы узнаете, как избежать типовых ошибок и построить устойчивую интеграцию.
Какие лимиты установлены в API Битрикс24?
Битрикс24 применяет ограничения на двух уровнях:
| Тип | Лимит | Комментарий |
|---|---|---|
| Вебхуки (входящие) | 2 запроса в секунду | На один вебхук |
| Серверные приложения (OAuth) | 2 запроса в секунду | На одно приложение на один портал |
| Суточный лимит | 10 000 запросов в сутки | Для бесплатных тарифов. Коммерческие — выше |
| batch-запрос | 50 команд в одном batch | Считается как 1 запрос к API |
При превышении лимита API возвращает HTTP 503 с телом {"error":"QUERY_LIMIT_EXCEEDED"}. Повторный запрос рекомендуется через 500 мс — но не сразу. Суточный лимит сбрасывается в 00:00 по времени портала. Для приложений из маркетплейса лимиты отличаются и зависят от подписки разработчика.
Как метод batch помогает обойти лимиты?
batch — главный инструмент экономии запросов. Один вызов batch содержит до 50 команд и считается как один запрос:
POST https://your-domain.bitrix24.by/rest/batch/ cmd[0]=crm.deal.list?filter[STAGE_ID]=WON cmd[1]=crm.deal.list?filter[STAGE_ID]=LOSE cmd[2]=crm.contact.list?filter[TYPE_ID]=CLIENT Команды внутри batch выполняются последовательно. Можно использовать результаты предыдущих команд через $result:
cmd[0]=crm.deal.get?id=123 cmd[1]=crm.contact.get?id=$result[0][CONTACT_ID] Batch-запросы позволяют выполнить до 50 операций за один запрос — это в 50 раз эффективнее последовательных вызовов. Вместо 50 отдельных запросов (25 секунд при 2 req/sec) — один запрос за 1-2 секунды.
Сравнение стратегий управления лимитами
| Стратегия | Сложность | Надёжность | Применимость |
|---|---|---|---|
| Exponential backoff | Низкая | Средняя | Простые сценарии |
| Очередь запросов | Средняя | Высокая | Высоконагруженные |
| Token bucket | Высокая | Высокая | Распределённые системы |
Exponential backoff — при получении QUERY_LIMIT_EXCEEDED повторять запрос с увеличивающейся задержкой: 500 мс → 1 с → 2 с → 4 с. Максимум 5 попыток, потом — ошибка в лог.
Очередь запросов — вместо прямых вызовов API запросы ставятся в очередь (Redis, RabbitMQ, БД). Воркер разбирает очередь, соблюдая интервал 500 мс между запросами. Это исключает ситуацию, когда два процесса одновременно шлют запросы и суммарно превышают лимит.
Token bucket — программный счётчик: приложение отслеживает количество запросов за последнюю секунду и блокирует отправку до освобождения слота. Реализуется через shared state (Redis) для распределённых систем.
Также применяйте разделение по времени: тяжёлые синхронизации (полная выгрузка сделок, обновление каталога) выполняйте ночью, когда пользователи не работают с API.
Как выбрать стратегию управления лимитами?
Выбор стратегии зависит от нагрузки и архитектуры. Для простых сценариев достаточно exponential backoff — он не требует дополнительных сервисов. Если интеграция высоконагруженная (более 10 запросов в секунду суммарно), используйте очередь запросов на Redis — она гарантирует соблюдение лимитов даже при конкурентных запросах. Token bucket подходит для распределённых систем, где несколько микросервисов обращаются к одному порталу.
Как проверить текущий расход API?
Текущий расход API-вызовов можно проверить методом `app.info` — возвращает количество оставшихся запросов за текущий период. Для вебхуков аналогичной метрики нет — нужно считать на своей стороне. В логах Б24 (раздел Настройки → Журнал событий) фиксируются ошибки API, включая превышение лимитов. Настраиваем алерт при достижении 80% суточного лимита.Что входит в работу
- Архитектура интеграции с учётом rate limits: batch-запросы, очереди, backoff
- Воркер для последовательной обработки API-запросов с контролем скорости
- Переход с одиночных запросов на batch для массовых операций
- Мониторинг расхода API-лимитов и алерты при приближении к порогу
- Разнесение нагрузки: фоновые синхронизации в непиковое время
- Диагностика и устранение ошибок
QUERY_LIMIT_EXCEEDED - Документация по настроенной интеграции
Оценка проекта — бесплатно. Если вы столкнулись с ошибками QUERY_LIMIT_EXCEEDED или хотите оптимизировать API-интеграцию, свяжитесь с нами. Наши сертифицированные специалисты имеют многолетний опыт работы с Битрикс24 и гарантируют стабильность ваших интеграций. Получите консультацию — мы поможем устранить узкие места и предотвратить простои.