Настройка rate-limiting для API Битрикс24
Интеграция работает, данные синхронизируются — а потом в пятницу вечером скрипт начинает слать запросы в цикле без пауз, упирается в лимит, получает ошибку QUERY_LIMIT_EXCEEDED и падает. Или хуже — не падает, а повторяет запрос немедленно, усугубляя ситуацию. API Битрикс24 имеет жёсткие rate limits, и любая интеграция обязана их учитывать. Иначе — потеря данных, рассинхронизация, блокировка приложения.
Лимиты REST 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]
Вместо 50 отдельных запросов (25 секунд при 2 req/sec) — один запрос за 1-2 секунды.
Стратегии работы с лимитами
Exponential backoff — при получении QUERY_LIMIT_EXCEEDED повторять запрос с увеличивающейся задержкой: 500 мс → 1 с → 2 с → 4 с. Максимум 5 попыток, потом — ошибка в лог.
Очередь запросов — вместо прямых вызовов API запросы ставятся в очередь (Redis, RabbitMQ, БД). Воркер разбирает очередь, соблюдая интервал 500 мс между запросами. Это исключает ситуацию, когда два процесса одновременно шлют запросы и суммарно превышают лимит.
Token bucket — программный счётчик: приложение отслеживает количество запросов за последнюю секунду и блокирует отправку до освобождения слота. Реализуется через shared state (Redis) для распределённых систем.
Разделение по времени — тяжёлые синхронизации (полная выгрузка сделок, обновление каталога) выполняются ночью, когда пользователи не работают с API.
Мониторинг расхода
Текущий расход API-вызовов можно проверить методом app.info — возвращает количество оставшихся запросов за текущий период. Для вебхуков аналогичной метрики нет — нужно считать на своей стороне.
В логах Б24 (раздел Настройки → Журнал событий) фиксируются ошибки API, включая превышение лимитов. Рекомендуем настроить мониторинг: алерт при достижении 80% суточного лимита.
Что настраиваем
- Архитектура интеграции с учётом rate limits: batch-запросы, очереди, backoff
- Воркер для последовательной обработки API-запросов с контролем скорости
- Переход с одиночных запросов на batch для массовых операций
- Мониторинг расхода API-лимитов и алерты при приближении к порогу
- Разнесение нагрузки: фоновые синхронизации в непиковое время
- Диагностика и устранение ошибок
QUERY_LIMIT_EXCEEDED