Настройка обработки ошибок интеграций Битрикс24

Настройка обработки ошибок интеграций Битрикс24

Интеграция, которая падает молча — хуже, чем отсутствие интеграции. Менеджер думает, что заявка ушла в склад, а она застряла в очереди с ошибкой авторизации три дня назад. Правильная обработка ошибок — это не красивые сообщения, а система, которая знает о проблеме раньше, чем пожалуется клиент.

Типология ошибок в интеграциях Битрикс24

Ошибки API Битрикс24. Коды ответа: 200 с полем error в теле (логическая ошибка), 401 (токен истёк), 429 (превышен лимит запросов), 503 (сервис временно недоступен). Каждый тип требует своей реакции.

Ошибки внешней системы. Логистика вернула 400 Bad Request (неверный адрес), банковский API — 422 Unprocessable Entity (ИНН не найден). Это бизнес-ошибки, которые требуют внимания сотрудника, а не автоматического повтора.

Ошибки трансформации данных. Маппинг данных из Битрикс24 в формат внешней системы — поле обязательное, но пустое. Или тип данных не совпадает. Такие ошибки возникают при изменении структуры данных в одной из систем.

Сетевые ошибки. Таймаут соединения, DNS не резолвится, SSL-ошибка. Обычно временные, подходят для автоматического повтора.

Структура обработки

Для каждого интеграционного потока определяем три вещи: что считается ошибкой, как реагируем, кого уведомляем.

Логирование. Каждый запрос к внешней системе и его ответ фиксируются в лог. Минимальный набор: timestamp, метод, входные данные (с маскированием чувствительных полей), статус ответа, тело ошибки, время выполнения. В Битрикс24 можно использовать штатный механизм \Bitrix\Main\Diag\Debug::writeToFile() или внешний стек (Monolog → ELK).

Классификация ошибки. В обработчике ошибок определяем, к какому классу относится проблема:

switch (true) {
    case $e instanceof RateLimitException:
        // Ждём и повторяем
        $this->scheduleRetry($job, delay: 60);
        break;
    case $e instanceof AuthException:
        // Обновляем токен и повторяем
        $this->refreshToken();
        $this->scheduleRetry($job, delay: 5);
        break;
    case $e instanceof ValidationException:
        // Это бизнес-ошибка — уведомляем менеджера
        $this->notifyManager($job, $e->getMessage());
        $this->markFailed($job);
        break;
    case $e instanceof NetworkException:
        // Временная проблема — retry с экспоненциальной задержкой
        $this->scheduleRetry($job, delay: $job->getBackoffDelay());
        break;
}

Уведомления. Бизнес-ошибки (данные не прошли валидацию, контрагент не найден) — уведомляем ответственного менеджера через im.notify.system.add в Битрикс24. Системные ошибки (сервис недоступен, ошибка авторизации) — уведомляем технический персонал через Telegram-бота или почту.

Дашборд ошибок

Для поддержки интеграции нужен интерфейс просмотра ошибочных операций. Реализуется как встроенное приложение Битрикс24 или отдельный административный интерфейс. Показывает:

• Список зависших операций с описанием ошибки
• Возможность повторить операцию вручную
• История попыток с ответами внешней системы

Альтернатива: таблица ошибок в пользовательском инфоблоке или смарт-процессе Битрикс24 — тогда ответственный видит ошибки прямо в CRM без отдельного интерфейса.

Мониторинг и алерты

Настройка обработки ошибок — это 20% кода, который спасает 80% нервов при эксплуатации интеграции. Системы, где обработка ошибок не предусмотрена, требуют ручного вмешательства при каждой проблеме и накапливают «потерянные» операции, которые не выполнились и никому не сообщили об этом.