Обработка ошибок Tracking API: как управлять недействительными номерами отслеживания, ограничениями частоты запросов и повторными попытками

Обрабатывайте ошибки Tracking API, разделяя недопустимые входные данные, временные сбои, ограничения частоты запросов и результаты статуса отправления. Отклоняйте или исправляйте недействительные номера отслеживания вместо повторной отправки их без изменений, регулируйте объем запросов при ограничении частоты и повторяйте запросы при временных сбоях с ограниченной экспоненциальной задержкой и джиттером. Перед повторением регистрации или другого запроса на запись установите, была ли успешной первая попытка.

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

Классифицируйте сбой перед выбором ответа

Интеграция отслеживания имеет несколько отдельных результатов, которые необходимо оценивать: завершился ли сетевой запрос, принял ли API операцию, успешно ли обработан каждый запрошенный объект отслеживания и доступны ли события отправления. Если рассматривать все четыре аспекта как единый флаг успеха или сбоя, это приведет к ошибкам, которых можно избежать.

Успешный ответ HTTP не обязательно означает, что каждый объект в пакетном запросе был обработан успешно. И наоборот, успешно обработанный запрос без событий отслеживания не обязательно означает сбой API. Изучайте тело ответа и применяйте задокументированное поставщиком значение каждого результата.

Условие	Рекомендуемое действие	Повторить без изменений?
Неправильный номер или недопустимое поле запроса	Проверить и исправить входные данные	Нет
Отсутствующие или недействительные учетные данные	Проверить учетные данные, разрешения и среду	Только после исправления
Ответ об ограничении частоты запросов	Отложить затронутые операции и снизить общую нагрузку запросов	После обязательного ожидания, если это безопасно
Временный сбой сервиса	Применить ограниченную задержку и проверить безопасность операции	Обычно да, в пределах бюджета повторных попыток
Тайм-аут после отправки регистрации	Проверить, существует ли регистрация	Не вслепую
Принятый запрос без событий отправления	Следовать задокументированному жизненному циклу отслеживания	Использовать плановое обновление, а не частые повторы

Коды состояния HTTP являются отправной точкой, но не полной схемой принятия решений для конкретного поставщика. RFC 9110 определяет семантику HTTP, а RFC 6585 — 429 Too Many Requests. Ваша интеграция также должна интерпретировать задокументированные коды ошибок приложения и результаты на уровне отдельных объектов.

Недействительные номера отслеживания: отличайте неверные входные данные от отсутствующих событий

«Недействительный номер отслеживания» может означать разные проблемы: неправильный идентификатор, неподдерживаемое сочетание перевозчика и номера, отсутствие обязательного поля перевозчика или другую специфичную для поставщика ошибку проверки. Не предполагайте, что номер недействителен только потому, что события отслеживания не возвращены.

Проверяйте, не повреждая идентификатор

• Храните номера отслеживания как строки. Числовое хранение может удалить ведущие нули или изменить длинные идентификаторы.
• Сохраняйте исходные входные данные. Храните отдельное нормализованное значение, чтобы преобразования можно было проверить.
• Нормализуйте консервативно. При необходимости удаляйте пробелы по краям, но удаляйте внутренние символы или изменяйте регистр букв только в соответствии с задокументированными правилами.
• Проверяйте обязательные поля локально. Обнаруживайте пустые номера, отсутствующие идентификаторы перевозчика и недопустимую структуру запроса до его отправки.
• Избегайте универсального регулярного выражения для номеров отслеживания. Правило, разработанное для одного перевозчика, может отклонить действительные идентификаторы другого.
• Уточняйте содержимое поля. Номер заказа, складской идентификатор и номер отслеживания перевозчика не взаимозаменяемы, если конечная точка явно не поддерживает их.

Если API явно отклоняет входные данные, направьте их на исправление, а не в цикл автоматических повторов. Указывайте полезную причину, например «требуется идентификатор перевозчика», вместо сведения любой проблемы проверки к сообщению «отслеживание не удалось».

Рассматривайте состояние «нет событий» отдельно

У отправления может уже быть идентификатор отслеживания, когда полезные события перемещения еще недоступны. Правильный ответ зависит от задокументированной модели статусов API и контекста отправления. Проверьте, поступил ли идентификатор из системы доставки, правильно ли выбран перевозчик и указывает ли ответ на ожидание данных, а не на отклонение входных данных.

Используйте отдельные внутренние состояния, такие как input_rejected, awaiting_events и temporarily_unavailable. Это предлагаемые состояния приложения, а не стандартизированные значения API. Они помогают предотвратить превращение временного отсутствия данных в неточное сообщение клиенту.

Управляйте ограничениями частоты во всей интеграции, а не отдельно для каждого обработчика

RFC 6585 определяет HTTP 429 как ответ об ограничении частоты запросов и допускает наличие заголовка Retry-After. Стандарт не устанавливает универсальное ограничение или метод подсчета для Tracking API. Ограничения могут быть задокументированы для учетной записи, учетных данных, конечной точки или другой области; используйте фактические правила поставщика.

RFC 9110 определяет два формата Retry-After: неотрицательное количество секунд или дату HTTP. Обрабатывайте оба формата. Если указана дата, тщательно рассчитывайте оставшееся время ожидания и учитывайте различия часов. Если значение отсутствует или непригодно для использования, применяйте настроенную резервную политику задержки.

Недостаточно, чтобы один обработчик просто ожидал, пока другие продолжают использовать тот же лимит. Разместите управление частотой на общей границе для соответствующих учетных данных или учетной записи. Центральный планировщик, общий токен-ведро или эквивалентный распределенный механизм управления могут координировать этот трафик.

1. Определите затронутую область. Установите, к какой конечной точке, учетным данным или учетной записи применяется ограничение.
2. Соблюдайте указание сервера по ожиданию. Не планируйте повторную попытку раньше срока, разрешенного действительным значением Retry-After.
3. Отложите затронутые операции в очереди. Не блокируйте независимый трафик, если ограничения действительно не связаны между собой.
4. Снизьте параллелизм или частоту запросов. Однократное ожидание без изменения схемы запросов может привести к повторению той же проблемы.
5. Возобновляйте работу с интервалами. После окончания ожидания не выпускайте всю очередь одновременно.

Если поддерживается пакетная обработка, она может сократить количество запросов, но должна соответствовать задокументированным ограничениям размера пакета и правилам учета. Не предполагайте, что один пакет расходует одну единицу лимита. Аналогично, используйте вебхуки, если они доступны, чтобы сократить избыточный опрос, сохраняя необходимый интеграции процесс сверки.

Используйте ограниченные повторы с задержкой и джиттером

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

Практический резервный вариант — ограниченная экспоненциальная задержка с полным джиттером:

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

Здесь retry_index начинается с нуля для первой повторной попытки, а отсутствующий Retry-After не добавляет минимального времени ожидания. Это варианты реализации, а не обязательный алгоритм HTTP. Выбирайте базовую задержку, предел, количество попыток и общий крайний срок с учетом вашей рабочей нагрузки и рекомендаций поставщика.

Джиттер распределяет запросы во времени, вместо того чтобы каждый обработчик повторял их по одному расписанию. Ограничение задержки ограничивает экспоненциальную составляющую; оно не должно отменять более длительное действительное ожидание, запрошенное сервером. Если такое ожидание превышает крайний срок задания, отложите или завершите задание согласно политике, а не повторяйте запрос раньше времени.

Задайте предел для каждой цепочки повторов

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

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

Устраняйте неоднозначность операций записи перед их повторной отправкой

Тайм-аут означает, что приложение не получило полный ответ. Он не доказывает, что сервер отклонил запрос или вообще его не обработал. Это различие важно при регистрации номеров отслеживания или изменении конфигурации отслеживания.

RFC 9110 объясняет идемпотентные методы и предостерегает от автоматического повтора неидемпотентных запросов без оснований считать повтор безопасным или знать, что исходная операция не была применена. Оценивайте задокументированную семантику операции, а не предполагайте, что каждая конечная точка отслеживания работает как запрос только для чтения.

• Используйте задокументированный поставщиком механизм идемпотентности, если он доступен, соблюдая его область действия и правила хранения.
• Сохраняйте один и тот же ключ идемпотентности для повторов одной логической операции; не предполагайте, что произвольный пользовательский заголовок будет принят.
• Если это поддерживается, проверьте существующую регистрацию перед повторением неоднозначной операции записи.
• Используйте локальное ограничение уникальности, согласованное с задокументированной идентичностью отправления у поставщика.
• Сохраняйте результат операции, чтобы повторная доставка из очереди автоматически не запускала еще одну запись.

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

Применяйте политику к своему поставщику отслеживания

Для интеграции с 17TRACK используйте страницу Tracking API и официальную документацию API как отправные точки для изучения специфики договора с поставщиком. Сделайте классификатор ошибок конфигурируемым, а не жестко кодируйте предположения из общего руководства по HTTP.

До начала реализации подтвердите схему запроса соответствующей конечной точки, оболочку ответа, значения ошибок на уровне объектов, область ограничения частоты, ограничения пакетной обработки и правила для повторных отправок. Если вы используете доставку событий, также проверьте требования к подтверждению, аутентификации и повторной доставке. Это руководство не устанавливает числовое ограничение частоты 17TRACK, расписание повторов или функцию идемпотентности.

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

Отслеживайте качество восстановления и тестируйте пути сбоев

Регистрируйте операцию, конечную точку, статус HTTP, код ошибки приложения, номер попытки, задержку, следующее запланированное действие и идентификатор запроса поставщика, если он предоставляется. Не записывайте ключи API, ненужную информацию об адресах или неограниченные тела ответов. Маскируйте или хешируйте идентификаторы отслеживания, если полные значения не нужны.

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

Перед выпуском протестируйте неправильные входные данные, действительные идентификаторы без событий, оба формата Retry-After, отсутствующие заголовки, частичные сбои пакетных операций, тайм-ауты после операций записи и повторную доставку из очереди. Также смоделируйте достаточно длительный сбой, чтобы исчерпать бюджет повторных попыток. Тест считается пройденным только тогда, когда работа предсказуемо останавливается или откладывается, успешные объекты не воспроизводятся без необходимости, а неудачные объекты остаются доступными для восстановления.

Часто задаваемые вопросы

Следует ли автоматически повторять запрос для недействительного номера отслеживания?

Нет, если API явно отклоняет входные данные как недействительные. Сначала исправьте номер, выбор перевозчика или обязательные поля. Если же ответ означает, что события отправления еще недоступны, используйте задокументированный процесс обновления, а не рассматривайте это как ошибку проверки.

Означает ли HTTP 200, что пакетный запрос полностью выполнен успешно?

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

Сколько повторных попыток должна разрешать интеграция отслеживания?

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

Следует ли немедленно помечать отправление как неудачное при тайм-ауте?

Нет. Тайм-аут запроса — это результат интеграции, а не событие отправления. Сохраняйте последнее известное состояние отслеживания, планируйте безопасное восстановление и не превращайте проблему соединения в уведомление о сбое доставки.

Что делать после исчерпания повторных попыток?

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

Источники

• RFC 9110: HTTP Semantics — семантика статусов HTTP, идемпотентные методы, рекомендации по автоматическим повторам и поле Retry-After.
• RFC 6585: Additional HTTP Status Codes — определение 429 Too Many Requests и необязательного заголовка Retry-After.
• 17TRACK Tracking API — официальная отправная точка для продукта Tracking API.
• 17TRACK API documentation — справочник для проверки специфических требований к интеграции поставщика.