Обработка на грешки в 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. Продължете с интервали. Не освобождавайте целия backlog едновременно, когато изчакването приключи.

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

Използвайте ограничени повторения с изчакване и случайно отклонение

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

Практичен резервен вариант е ограничено експоненциално изчакване с пълно случайно отклонение:

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 — справочник за проверка на специфичните изисквания за интеграция на доставчика.