Вебхук Битрикс24 не работает: разбор ответов
Ошибку REST API определяют по составу полей в теле ответа, а не по HTTP-статусу: со статусом 200 приходят ошибки подзапросов пакета batch. Если в теле есть error и error_description — вызов не выполнен. Если непустое result.result_error — пакет принят, но часть подзапросов упала.
Вебхук не найден или не авторизован
- INVALID_CREDENTIALS (401) — активного вебхука с такой парой «идентификатор пользователя и секретный код» нет. Проверьте адрес целиком: чаще всего в нём лишний или потерянный символ, либо вебхук удалили.
- NO_AUTH_FOUND (401) — в запросе вообще нет кода вебхука.
- INVALID_REQUEST,
Https required— вызов ушёл по http. - ACCESS_DENIED — REST недоступен на текущем тарифе; у вебхука текст звучит как
REST is available only by subscription. - insufficient_scope — вебхуку не выдали право, которое нужно методу. Права правят в настройках самого вебхука.
- ERROR_METHOD_NOT_FOUND (404) — опечатка в имени метода либо отсутствующее право.
- PORTAL_DELETED (403) — в коробке закрыта публичная часть сайта. Пока она закрыта, REST не ответит.
Отдельно стоит OVERLOAD_LIMIT (401): это ручная блокировка REST за перегрузку. Сама она не снимется, повторять вызовы бессмысленно — нужно обращение в поддержку вендора.
Два лимита, о которые разбиваются выгрузки
Интенсивность запросов. Работает по принципу протекающего ведра: каждый вызов добавляет единицу к счётчику, счётчик убывает со своей скоростью. На обычных тарифах это 2 запроса в секунду при пороге 50, на Энтерпрайзе — 5 в секунду при пороге 250. Короткий всплеск допустим, постоянное превышение — нет: за порогом приходит 503 и QUERY_LIMIT_EXCEEDED. Лимит считается на портал, поэтому две интеграции с одного сервера делят его между собой.
Ресурсоёмкость. У каждого метода накапливается время выполнения — поле operating в блоке time ответа. Учёт идёт десятью минутными корзинами; когда накопленное время превышает лимит, следующий вызов этого метода блокируется с 429 и кодом OPERATION_TIME_LIMIT. Блокируется только этот метод для этого вебхука, остальное работает. Когда делать повторную попытку, подсказывает operating_reset_at из последнего успешного ответа.
Для масштаба: 2 запроса в секунду — это 172 800 вызовов в сутки, а списочные методы отдают по 50 записей за раз. Для большинства выгрузок этого достаточно, если не запускать их в десять потоков.
Пакет batch
В один batch помещается до 50 вызовов, и это главный способ не превышать интенсивность: один HTTP-запрос вместо пятидесяти. Ресурсоёмкость вложенных методов он не отменяет. Подзапросы сверх пятидесяти получают ERROR_BATCH_LENGTH_EXCEEDED, а метод, который нельзя выполнить в пакете, — ERROR_BATCH_METHOD_NOT_ALLOWED. Ошибка подзапроса приходит по тому же ключу, под которым команда передана.
Коробочная версия
В коробке лимиты другие: интенсивность и нагрузку настраивает администратор, а лимит ресурсоёмкости по умолчанию выключен — при включении он равен 420 секундам и меняется в настройках модуля REST. Время выполнения запроса зависит от настроек сервера, тогда как в облаке запрос обрывается на 60 секундах.
Чего не делать
- Не повторять вызов, который вернул ошибку метода: ответ будет тот же, сначала правят запрос.
- Не ветвить логику по тексту
error_description— он меняется и зависит от языка. - Не писать код вебхука в журналы: по нему получают доступ к данным портала. В журнал идут код ошибки, описание, статус и имя метода.
Проверяли по первоисточнику: документация REST API Битрикс24
Частые вопросы
Вебхук работал, после смены сотрудника перестал.
Вебхук привязан к пользователю, который его создал, и работает с его правами. Уволили сотрудника — вебхук перестал отвечать. Поэтому вебхуки для интеграций создают от учётной записи, которая не уйдёт вместе с человеком.
Выгрузка падает на середине с кодом 503.
Это QUERY_LIMIT_EXCEEDED — превышена интенсивность запросов. Снизьте частоту, повторяйте с нарастающей задержкой и не запускайте параллельные серии: лимит считается на портал целиком, а не на вашу программу.
Один метод заблокирован, остальные работают.
Так выглядит OPERATION_TIME_LIMIT со статусом 429: превышен лимит ресурсоёмкости для этого метода у этого вебхука. Блокировка снимается сама, ориентир для повторной попытки — поле operating_reset_at из последнего успешного ответа.
