Разбор ошибок интеграции по этапу операции
Версия 2.7
Отделите проверку данных от транспорта
Сохраните, на каком этапе произошёл сбой: подготовка заказа, исходящий запрос, выпуск этикетки, получение события или обновление локальной записи. Для каждой попытки фиксируйте код продукта и HTTP-статус раздельно. Код продукта помогает выбрать процедуру, а HTTP-статус описывает результат сетевого обмена. Например, тайм-аут клиента может не содержать ответа сервера.
Ошибки, требующие изменения данных
При LBL-422 проверьте согласованность города и почтового индекса и исправьте адрес в черновике. При PICK-409 обновите список доступных окон и выберите другое. При PAY-402 проверьте баланс организации. Автоматический повтор с прежними данными здесь обычно не решает причину. Назначьте задачу тому, кто может исправить адрес, окно или баланс.
Ошибки доступа и подписи
При AUTH-403 владелец проверяет область доступа API-ключа. Успешное чтение статусов не подтверждает право на создание отправления. При HOOK-401 сравните секрет нужной среды и необработанное тело HTTP-запроса. Проверьте часы обработчика и передачу заголовков. Ключи и секреты для диагностики в обращение не включайте.
Ограничение частоты и неизвестный итог
При HTTP 429 следуйте Retry-After в секундах и ограничивайте дальнейшие повторы. При тайм-ауте создания выясните итог предыдущей операции. Повтор использует прежний Idempotency-Key и неизменное тело, а запись ключа хранится 24 часа. Решение о повторе должно учитывать тип действия: чтение состояния и создание отправления имеют разные последствия.
Когда нужна командная эскалация
Если одинаковый сбой воспроизводится на нескольких складах, проверьте страницу статуса в кабинете и сохраните идентификаторы запросов. Укажите время, затронутые действия, последний успешный шаг и масштаб. При неизвестном коде передайте точное значение и контекст, чтобы специалист мог его сопоставить. Похожие по форме коды могут описывать разные причины.
Разметка действий дежурного
В локальном журнале пометьте причину остановки и команду, которая может её устранить. Адрес исправляет оператор заказа, область ключа проверяет владелец, подпись разбирает инженер обработчика. Объединяйте события только после сравнения кода, этапа и времени. Одна и та же внешняя жалоба о неработающей доставке может включать разные сбои.
Восстановление после устранения причины
Возобновите сначала одну контролируемую задачу и проверьте результат по кабинету и журналу клиента. Затем выпускайте накопившиеся задачи небольшими группами. Для записей с неизвестным исходом сохраните прежнюю идентичность операции или передайте на сверку, когда срок защиты истёк. Для исправленных данных сохраните связь с предыдущей попыткой, чтобы оператор мог объяснить историю заказа.