Типовые ошибки

HTTP-коды от транспортного API

Код	Когда возникает	Что делать
400 Bad Request	Некорректный JSON-конверт при отправке	Проверить формат конверта: наличие полей Id, ClassId, Body
401 Unauthorized	Истёк access token	Обновить токен через POST /api/auth/refresh; если refresh истёк — пройти авторизацию заново
404 Not Found	Класс сообщения не зарегистрирован	Создать класс сообщения в Личном кабинете DataHUB
404 Not Found при ACK	AckId не найден	Сообщение уже подтверждено или TTL истёк; повторный ACK не нужен
408 Request Timeout	Таймаут long-polling	Нормальная ситуация — продолжить цикл получения
409 Conflict	Превышен лимит одновременно обрабатываемых сообщений	Дождаться завершения текущей обработки; снизить параллелизм
5xx	Внутренняя ошибка сервера	Проверить логи DataHUB; повторить запрос через паузу

Проблемы доставки

Сообщение отправлено, но получатель его не видит. Причины: - Не настроен маршрут в Личном кабинете от системы-отправителя к получателю. - Маршрут есть, но получатель не опрашивает шину (не работает регламентное задание). - Получатель опрашивает, но не выполняет ACK — сообщение висит «в полёте».

Сообщение приходит повторно. Причина — ACK не был отправлен или не был принят сервером. Это штатная ситуация при at-least-once доставке. Входящий обработчик обязан быть идемпотентным.

Проблемы идентификации объектов

Статус «Ошибка обработки», текст «Объект не найден». Объект ссылается на зависимость, которая ещё не пришла. Если ситуация не устраняется автоматически через retry — проверить, была ли зависимость отправлена и доставлена.

Статус «Ошибка обработки», текст про неоднозначность/конфликт. В одной из систем есть дублирующие записи с одинаковым идентификатором. Требует ручной очистки таблицы идентификаторов.

Статус «Отсутствует обработчик». Для класса сообщения не настроен входящий обработчик или он отключён. Проверить справочник «Объекты интеграции ДатаХаб».