Налаштування rate-limiting для API Bitrix24
Інтеграція працює, дані синхронізуються — а потім у п'ятницю вечером скрипт починає слати запити в цикл без пауз, натикається на ліміт, отримує помилку QUERY_LIMIT_EXCEEDED і падає. Або гірше — не падає, а повторює запит негайно, погіршуючи ситуацію. API Bitrix24 має жорсткі rate limits, і будь-яка інтеграція повинна їх враховувати. Інакше — втрата даних, розсинхронізація, блокування додатка.
Ліміти REST API Bitrix24
Bitrix24 застосовує обмеження на двох рівнях:
| Тип | Ліміт | Коментар |
|---|---|---|
| Вебхуки (вхідні) | 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 — програмний лічильник: додаток відстежує кількість запитів за останню секунду і блокує відправлення до звільнення слоту. Реалізується через спільний стан (Redis) для розподілених систем.
Розподіл за часом — важкі синхронізації (повна виїмка сделок, оновлення каталогу) виконуються вночі, коли користувачі не працюють з API.
Моніторинг видатків
Поточні видатки API-викликів можна перевірити методом app.info — повертає кількість залишених запитів за поточний період. Для вебхуків аналогічної метрики немає — потрібно рахувати на своїй стороні.
У логах Б24 (розділ Параметри → Журнал подій) фіксуються помилки API, включаючи перевищення лімітів. Рекомендуємо налаштувати моніторинг: сповіщення при досягненні 80% добового ліміту.
Що налаштовуємо
- Архітектура інтеграції з урахуванням rate limits: batch-запити, чергі, backoff
- Воркер для послідовної обробки API-запитів з контролем швидкості
- Перехід з одиничних запитів на batch для масових операцій
- Моніторинг видатків API-лімітів та сповіщення при наближенні до порога
- Розподіл навантаження: фонові синхронізації в непіковий час
- Діагностика та усунення помилок
QUERY_LIMIT_EXCEEDED