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

Обробляйте помилки 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. Стандарт не встановлює універсальний ліміт або метод підрахунку для 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 — семантика статусів HTTP, ідемпотентні методи, міркування щодо автоматичних повторних спроб і поле Retry-After.
• RFC 6585: Додаткові коди статусу HTTP — визначення 429 Too Many Requests і необов’язкового заголовка Retry-After.
• Tracking API 17TRACK — офіційна точка входу до продукту API відстеження.
• Документація API 17TRACK — довідка для перевірки специфічних вимог інтеграції постачальника.