Ми часто стикаємося з ситуацією: інтеграція працює, дані синхронізуються — а потім у п'ятницю ввечері скрипт починає слати запити в циклі без пауз, впирається в ліміт, отримує помилку 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 і гарантують стабільність ваших інтеграцій. Отримайте консультацію — ми допоможемо усунути вузькі місця та запобігти простоям.