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

Формат response_code

Все операции возвращают response_code в финальном ответе. Формат кода:

Диапазон / Формат	Источник	Описание
000	Эквайер/терминал	Операция выполнена успешно (Approved).
001–099	Эквайер/терминал	Предупреждения и специальные статусы эквайера.
100–999	Эквайер/терминал	Отказы эквайера (Declined). Подробности в response_desc.
DLL-***	LP Drive	Внутренние ошибки LP Drive (валидация параметров, логика, конфигурация).
NET-***	Инфраструктура	Сетевые и транспортные ошибки (соединение, таймауты, шлюз).
MSG-***	LP Drive	Ошибки обработки протокольных сообщений.
ACK-***	LP Drive	Ошибки подтверждения доставки.
TRX-***	LP Drive	Ошибки уровня транзакций.
COM-***	LP Drive	Ошибки COM-транспорта.
FLW-***	LP Drive	Ошибки управления потоком сообщений.

Коды ошибок — транспортный уровень (NET-*)

Код	Описание	Что делать	Транзакция
NET-001	LP Drive не может подключиться к IKR (неверный IP/порт или IKR недоступен).	Проверить запуск IKR и параметры tcp.host / tcp.port.	Прерывается.
NET-002	Потеря соединения во время обмена.	LP Drive автоматически выполнит переподключение (если включено). Повторить операцию.	Прерывается.
NET-003	Ошибка при записи в TCP-сокет.	Проверить сетевую доступность терминала.	Прерывается.
NET-004	Ошибка при чтении из TCP.	Проверить соединение и перезапустить операцию.	Прерывается.
NET-005	Нет данных в течение kkm.gateway.read.timeout.	Проверить связь с терминалом; увеличить таймаут при необходимости.	Прерывается.
NET-010	ККМ не может установить внешнее соединение.	Проверить интернет-доступность ККМ.	Прерывается.
NET-011	Внешний хост не отвечает.	Проверить доступность хоста эквайера.	Прерывается.
NET-012	Нет ответа в течение настроенного таймаута.	Увеличить kkm.gateway.read.timeout или проверить канал.	Прерывается.
NET-013	Несовместимые параметры kkm.gateway.*.	Исправить конфигурацию (kkm.gateway.mode должен быть корректным значением).	Прерывается.
NET-014	com_mux запрошен, но transport.mode = tcp.	Использовать com_mux только с transport.mode = com.	Прерывается.
NET-015	Превышен queue.network.max. Пакет отброшен.	Снизить частоту запросов или увеличить queue.network.max.	Прерывается.
NET-016	Не получено подтверждение доставки данных после исчерпания попыток повтора.	Проверить IKR и канал. Не повторять транзакцию автоматически — дождаться переустановки соединения.	Прерывается.
NET-017	Переполнен буфер входящих данных по одному соединению.	Снизить объём передаваемых данных или увеличить internet.receive.buffer.max.	Прерывается.

Коды ошибок — уровень сообщений (MSG-*)

Код	Описание	Транзакция
MSG-001	Невозможно выделить сообщение по разделителю.	Игнорируется без ACK.
MSG-002	Некорректное сообщение.	Игнорируется без ACK.
MSG-003	Отсутствует обязательное поле (message_type и др.).	Прерывается.
MSG-004	Неизвестный message_type.	Прерывается.
MSG-006	transaction_id не совпадает с активной транзакцией.	Прерывается.
MSG-007	Дубликат message_id (повтор).	Игнорируется.
MSG-008	Неверное значение transaction_type.	Прерывается.
MSG-009	Несоответствие типа или длины поля спецификации.	Прерывается.

Коды ошибок — уровень ACK (ACK-*)

Код	Описание	Транзакция
ACK-001	ACK не получен в течение ack.timeout.	Прерывается.
ACK-002	ACK не получен после ack.resend попыток.	Прерывается.
ACK-003	message_id в ACK не найден среди ожидаемых.	Прерывается.
ACK-005	LP Drive не отправила ACK (ошибка реализации).	Прерывается.

Коды ошибок — уровень транзакций (TRX-*)

Код	Описание	Транзакция
TRX-001	Параллельная транзакция: новый вызов при активной операции.	Прерывается.
TRX-002	Прерывание транзакции из-за потери соединения.	Прерывается.
TRX-003	Внутренняя ошибка IKR при выполнении операции.	Прерывается.
TRX-004	Повторная обработка: нарушение идемпотентности.	Прерывается.
TRX-005	Отмена по инициативе ККМ (получен cancel-запрос).	Прерывается.

COM-порт (COM-*)

Код	Описание	Что делать	Транзакция
COM-001	Не удаётся открыть COM-порт (занят или отсутствует).	Проверить com.port в конфигурации.	Прерывается.
COM-002	Невозможно применить настройки порта (baudrate, parity).	Проверить параметры com.* в конфигурации.	Прерывается.
COM-003	Ошибка при отправке данных через COM.	Проверить физическое подключение.	Прерывается.
COM-004	Ошибка при чтении из COM.	Проверить физическое подключение.	Прерывается.
COM-005	Физическое отключение COM-соединения.	Переподключить устройство.	Прерывается.
COM-006	Некорректный тип транспорта в конфигурации.	Проверить transport.mode.	Прерывается.

Коды ошибок — управление потоком (FLW-*)

Код	Описание	Что делать	Транзакция
FLW-001	Превышен лимит промежуточных статусов в очереди. IKR прекращает отправку статусов.	Убедиться, что ПО ККМ своевременно читает статусы через callback или polling.	Прерывается.
FLW-002	ACK получен вне ожидаемого порядка.	Проверить логи DLL на предмет нарушений последовательности.	Игнорируется.

Рекомендации по обработке ошибок в ПО ККМ

• Всегда проверяйте response_code в финальном ответе. Код 000 означает успех; любой другой — необходимость обработки отказа.
• Используйте response_desc для информирования кассира — он уже содержит готовый текст.
• NET- и DLL- коды являются инфраструктурными. Они не несут бизнес-результата операции и требуют технических действий: повтора, проверки соединения или конфигурации.
• Для автоматического повтора транзакций реализуйте логику с ограниченным числом попыток и задержкой (exponential backoff).
• При получении ошибок MSG-* проверьте корректность формата передаваемых параметров.
• Логируйте response_code, response_desc и transaction_id для каждой операции — это упрощает диагностику.