Очереди и ретраи: как не терять данные при сбоях
Интеграция с Битрикс24 через REST API кажется простой: отправил запрос, получил ответ. Но в реальной работе всё сложнее. Лимиты интенсивности, таймауты, пиковая нагрузка, сбои сети — всё это может привести к потере данных. Если сделка не создалась или событие не обработалось, бизнес теряет деньги.
По данным официальной документации, лимит интенсивности для большинства тарифов — 2 запроса в секунду. При превышении — ошибка `QUERY_LIMIT_EXCEEDED`. Один запрос должен выполняться не дольше 60 секунд. А события, которые отправляет Битрикс24, доставляются через отдельный сервис, и если обработчик не ответил — событие не переотправляется.
В этой статье — как построить интеграцию, которая не теряет данные: очереди, ретраи, идемпотентность, батчинг. Если нужна разработка надёжной интеграции через API — поможем.
Содержание статьи
Лимиты интенсивности
Битрикс24 ограничивает интенсивность запросов к REST API. Это защита от перегрузки, и она действует на всех.
| Тариф | Устойчивая интенсивность | Порог блокировки | Ошибка |
|---|---|---|---|
| Энтерпрайз | 5 запросов/сек | 250 | QUERY_LIMIT_EXCEEDED (503) |
| Остальные | 2 запроса/сек | 50 | QUERY_LIMIT_EXCEEDED (503) |
Как это работает
Лимит работает по принципу Leaky Bucket. Каждый запрос увеличивает счётчик. Когда счётчик превышает порог, следующий запрос блокируется. Счётчик уменьшается на Y в секунду. При интенсивности не более Y запросов в секунду ошибки не будет.
Что важно
- Учитываются HTTP-запросы — не количество записей в ответе;
- IP-адрес — если несколько приложений на одном сервере, они делят общий лимит;
- Кратковременные всплески — допустимы, но нельзя поддерживать высокую интенсивность постоянно.
💡 Важно
При интенсивности 2 запроса в секунду за сутки можно выполнить 172 800 запросов. Этого достаточно для большинства интеграций, если не делать лишних вызовов.
Таймауты
В облачном Битрикс24 один REST-запрос должен выполниться не дольше чем за 60 секунд. Если дольше — запрос прерывается.
Что влияет на длительность
- Объём данных — большие выборки выполняются дольше;
- Сложность фильтров — сложные условия замедляют запрос;
- Вложенные вызовы в batch — каждый метод внутри пакета расходует время;
- Автоматизация — если метод запускает роботов или бизнес-процессы.
Как избежать
- Разбивайте большие операции — несколько маленьких запросов безопаснее одного тяжёлого;
- Используйте постраничную выборку — не запрашивайте всё сразу;
- Запрашивайте только нужные поля — параметр `select`;
- Следите за временем в ответе — поле `duration` в объекте `time` .
Батчинг
Метод `batch` позволяет передать до 50 вызовов методов в одном HTTP-запросе. Для лимита интенсивности это считается как один запрос.
Когда использовать
- Много независимых вызовов — например, обновить 50 контактов;
- Выборка данных — 50 вызовов `list` по 50 записей вернут 2500 записей за один HTTP-запрос;
- Снижение нагрузки на лимит — вместо 50 запросов один.
Ограничения
`batch` сокращает число HTTP-запросов, но не уменьшает ресурсоёмкость методов внутри пакета. Если каждый метод тяжёлый, пакет может не уложиться в таймаут.
💡 Важно
Не используйте `batch` для операций, которые должны выполняться строго последовательно с проверкой результата. Если один метод в пакете упадёт, остальные всё равно выполнятся.
Входящая очередь
События от Битрикс24 доставляются через отдельный сервис — очередь событий. Интенсивность вызовов обработчика зависит от действий пользователей, и её нельзя регулировать. Если 10 000 сделок обновились одновременно — будет 10 000 вызовов .
Почему нужна своя очередь
Битрикс24 не переотправляет событие, если обработчик не ответил или вернул ошибку. Часть событий будет потеряна. Кроме того, медленный обработчик получает пониженный приоритет — следующие вызовы приходят с большими паузами .
Как построить
Ответить 2xx
Сразу, до обработки. Это сигнал «принято».
Сохранить в очередь
БД, Redis, RabbitMQ, Kafka — на выбор.
Обработать асинхронно
Воркеры забирают из очереди и выполняют.
Ретраи
При сбое — повторить с задержкой.
Такая схема удерживает время ответа коротким, позволяет управлять нагрузкой и масштабировать обработку.
Идемпотентность
Повторная доставка события возможна. Если обработчик уже обработал событие, а оно пришло снова — это не должно привести к дублированию данных.
Как обеспечить
- Уникальный ключ — сохранять ID события или объекта и проверять, не обработано ли уже;
- Окно дедупликации — не хранить ключи вечно, иначе реальные изменения будут заблокированы;
- Проверка состояния — если задача уже в нужном статусе, не менять повторно.
Пример: обработчик получает событие `OnCrmDealUpdate` с ID сделки. Он проверяет, не обрабатывал ли уже это событие за последние 5 минут. Если да — пропускает. Если нет — обрабатывает и запоминает.
Ретраи
Не все ошибки нужно повторять. И не все — сразу.
Что повторять
- `QUERY_LIMIT_EXCEEDED` — подождать и повторить;
- Сетевые ошибки — таймаут, обрыв соединения;
- 5xx от сервера — временная проблема.
Что не повторять
- 4xx (кроме 429) — ошибка в запросе, повтор не поможет;
- `insufficient_scope` — нет прав, нужно менять настройки;
- `WRONG_AUTH_TYPE` — метод недоступен через вебхук.
Как повторять
Экспоненциальная задержка с джиттером: 1 сек, 2 сек, 4 сек, 8 сек… плюс случайная добавка, чтобы ретраи от разных клиентов не приходили одновременно.
💡 Важно
Для операций записи (создание, обновление) ретрай должен быть идемпотентным. Иначе при повторной отправке создастся дубль. Используйте уникальные ключи или проверяйте состояние перед записью.
Наши рекомендации
Что вы получаете, заказывая разработку у нас
- Аудит лимитов — где узкие места
- Батчинг — сокращение запросов
- Входящую очередь — БД, Redis или брокер
- Идемпотентность — защита от дублей
- Ретраи — с задержкой и логированием
📌 Итоговый вывод
Надёжная интеграция — это не «отправил и забыл». Это лимиты, очереди, идемпотентность и ретраи.
Что нужно знать:
- Лимиты: 2 запроса/сек для большинства, 5 для Энтерпрайз. Ошибка `QUERY_LIMIT_EXCEEDED`;
- Таймауты: 60 секунд на запрос. Дробите большие операции;
- Батчинг: до 50 вызовов в одном HTTP-запросе;
- Входящая очередь: ответ 2xx → сохранить → обработать асинхронно;
- Идемпотентность: повторная доставка не должна дублировать данные;
- Ретраи: только для временных ошибок, с экспоненциальной задержкой.
Также рекомендуем: API, методы REST API, вебхуки, все статьи об API.