Обработка ошибок

Ошибки транспортного слоя

Ошибки при взаимодействии с Transport API обрабатываются адаптером автоматически. Разработчику прикладных обработчиков знать о них необязательно, но полезно понимать их природу.

Код	Причина	Действие адаптера
`204 No Content`	В очереди нет сообщений	Продолжить опрос (не ошибка)
`401 Unauthorized`	Access-токен истёк	Обновить через Refresh-токен и повторить
`408 Request Timeout`	Long-polling завершился без сообщений	Продолжить опрос (не ошибка)
`409 Conflict`	Превышен лимит неподтверждённых сообщений	Дождаться ACK предыдущих и повторить
`5xx`	Ошибка сервера DataHUB	Зафиксировать в логе, повторить позже

Если Refresh-токен тоже недействителен (401 при обновлении) — адаптер прекращает обмен. Требуется повторная авторизация.

Ошибки обработчиков

Прикладная ошибка в обработчике — основной тип ошибок, с которым работает разработчик интеграции.

Как обработчик сигнализирует об ошибке

Обработчик может сообщить платформе об ошибке двумя способами:

Необработанное исключение — автоматически переводит сообщение в режим повторной обработки.
Явный отказ — обработчик устанавливает флаг отказа, возвращая управление платформе без генерации исключения. Удобно для ожидаемых ситуаций — например, когда зависимый объект ещё не получен.

Цикл повторных попыток

При ошибке платформа не удаляет сообщение из очереди, а откладывает его:

Сообщение получает статус «Ожидание обработки» с задержкой (по умолчанию 30 секунд).
Счётчик попыток увеличивается на 1.
После истечения задержки фоновый процесс снова передаёт сообщение в обработчик.
Если счётчик превысил максимум (по умолчанию 5 попыток) — сообщение переводится в статус «Ошибка обработки» и исключается из автоматического цикла.

Оба параметра (задержка и максимум попыток) настраиваются в конфигурации модуля. Обработчик также может переопределить задержку для конкретного сообщения — это полезно для реализации экспоненциальной паузы или длительного ожидания зависимого объекта.

Статус «Ошибка обработки»

Сообщение в этом статусе:

не обрабатывается автоматически;
доступно для просмотра и ручного перезапуска;
сохраняет описание ошибки последней попытки.

Ручной перезапуск — стандартный инструмент восстановления. После исправления причины ошибки сообщения в этом статусе перезапускаются вручную.

Идемпотентность как обязательное требование

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

Подробнее — в Концепции / Идемпотентность и Отложенная обработка.