Obsługa błędów API śledzenia: jak zarządzać nieprawidłowymi numerami śledzenia, limitami zapytań i ponownymi próbami

Obsługuj błędy interfejsu API śledzenia, rozdzielając nieprawidłowe dane wejściowe, tymczasowe awarie, limity szybkości oraz wyniki dotyczące statusu przesyłki. Odrzucaj lub poprawiaj nieprawidłowe numery śledzenia zamiast ponawiać próbę bez zmian, koordynuj liczbę żądań po ograniczeniu szybkości oraz ponawiaj próby w przypadku tymczasowych awarii, stosując ograniczony wykładniczy czas oczekiwania z losowym opóźnieniem. Przed powtórzeniem rejestracji lub innego żądania zapisu ustal, czy pierwsza próba zakończyła się powodzeniem.

W przypadku deweloperów łączących dane śledzenia z systemem zarządzania zamówieniami, platformą magazynową lub stroną śledzenia przeznaczoną dla klientów celem nie jest po prostu zmniejszenie liczby nieudanych żądań. Chodzi o niezawodną widoczność przesyłek bez zduplikowanych rejestracji, lawin ponowień, mylących komunikatów o dostawie ani niepotrzebnych zgłoszeń do pomocy technicznej.

Sklasyfikuj awarię przed wyborem reakcji

Integracja śledzenia obejmuje kilka odrębnych rezultatów, które należy ocenić: czy żądanie sieciowe zostało zakończone, czy interfejs API zaakceptował operację, czy każdy żądany element śledzenia zakończył się powodzeniem oraz czy są dostępne zdarzenia dotyczące przesyłki. Traktowanie wszystkich czterech kwestii jako jednej flagi powodzenia lub niepowodzenia prowadzi do możliwych do uniknięcia błędów.

Pomyślna odpowiedź HTTP nie musi oznaczać, że każdy element partii zakończył się powodzeniem. Z drugiej strony pomyślnie przetworzone wyszukiwanie bez zdarzeń śledzenia nie musi oznaczać awarii interfejsu API. Sprawdzaj treść odpowiedzi i stosuj udokumentowane przez dostawcę znaczenie każdego wyniku.

Warunek	Zalecane działanie	Ponowić bez zmian?
Nieprawidłowy numer lub nieprawidłowe pole żądania	Zweryfikuj i popraw dane wejściowe	Nie
Brakujące lub nieprawidłowe dane uwierzytelniające	Sprawdź dane uwierzytelniające, uprawnienia i środowisko	Dopiero po poprawieniu
Odpowiedź o przekroczeniu limitu szybkości	Opóźnij zadania, których dotyczy problem, i zmniejsz wspólne obciążenie żądaniami	Po wymaganym oczekiwaniu, jeśli jest to bezpieczne
Tymczasowa awaria usługi	Zastosuj ograniczony czas oczekiwania i sprawdź bezpieczeństwo operacji	Zwykle tak, w ramach budżetu ponowień
Przekroczenie limitu czasu po przesłaniu rejestracji	Ustal, czy rejestracja istnieje	Nie w ciemno
Zaakceptowane wyszukiwanie bez zdarzeń przesyłki	Postępuj zgodnie z udokumentowanym cyklem życia śledzenia	Użyj zaplanowanego odświeżania, a nie szybkich ponowień

Kody statusu HTTP stanowią punkt wyjścia, a nie kompletny schemat decyzji właściwy dla konkretnego dostawcy. RFC 9110 definiuje semantykę HTTP, a RFC 6585 definiuje 429 Too Many Requests. Integracja powinna również interpretować udokumentowane kody błędów aplikacji oraz wyniki na poziomie poszczególnych elementów.

Nieprawidłowe numery śledzenia: odróżniaj błędne dane wejściowe od braku zdarzeń

Określenie „nieprawidłowy numer śledzenia” może opisywać różne problemy: nieprawidłowo sformatowany identyfikator, nieobsługiwaną kombinację przewoźnika i numeru, brak wymaganego pola przewoźnika lub inną właściwą dla dostawcy nieudaną walidację. Nie zakładaj, że numer jest nieprawidłowy tylko dlatego, że nie zwrócono żadnych zdarzeń śledzenia.

Weryfikuj bez uszkadzania identyfikatora

• Przechowuj numery śledzenia jako ciągi znaków. Przechowywanie numeryczne może usunąć początkowe zera lub zmienić długie identyfikatory.
• Zachowuj oryginalne dane wejściowe. Przechowuj oddzielną znormalizowaną wartość, aby transformacje można było poddać audytowi.
• Normalizuj zachowawczo. W razie potrzeby usuwaj otaczające białe znaki, ale usuwaj znaki wewnętrzne lub zmieniaj wielkość liter tylko wtedy, gdy pozwalają na to udokumentowane zasady.
• Sprawdzaj lokalnie wymagane pola. Wykrywaj puste numery, brakujące identyfikatory przewoźnika i nieprawidłowe struktury żądań przed ich wysłaniem.
• Unikaj uniwersalnego wyrażenia regularnego dla numerów śledzenia. Reguła zaprojektowana dla jednego przewoźnika może odrzucać prawidłowe identyfikatory innego przewoźnika.
• Potwierdź, co zawiera dane pole. Numer zamówienia, odwołanie magazynowe i numer śledzenia przewoźnika nie są wzajemnie wymienne, chyba że punkt końcowy wyraźnie je obsługuje.

Jeśli interfejs API wyraźnie odrzuca dane wejściowe, skieruj je do poprawy zamiast do automatycznej pętli ponowień. Podaj użyteczny powód, taki jak „wymagany identyfikator przewoźnika”, zamiast sprowadzać każdy problem z walidacją do komunikatu „śledzenie nie powiodło się”.

Traktuj „brak zdarzeń” jako odrębny stan

Przesyłka może mieć identyfikator śledzenia, zanim pojawią się użyteczne zdarzenia dotyczące jej przemieszczania. Właściwa reakcja zależy od udokumentowanego modelu statusów interfejsu API i kontekstu przesyłki. Sprawdź, czy identyfikator pochodzi z systemu wysyłkowego, czy wybrano właściwego przewoźnika oraz czy odpowiedź wskazuje na oczekujące dane, a nie odrzucone dane wejściowe.

Używaj odrębnych stanów wewnętrznych, takich jak input_rejected, awaiting_events i temporarily_unavailable. Są to sugerowane stany aplikacji, a nie ustandaryzowane wartości interfejsu API. Pomagają zapobiec przekształceniu tymczasowej luki w danych w nieprawidłowy komunikat dla klienta.

Zarządzaj limitami szybkości w całej integracji, a nie według pracownika

RFC 6585 definiuje HTTP 429 jako odpowiedź informującą o ograniczeniu szybkości i pozwala na dołączenie nagłówka Retry-After. Norma nie ustanawia uniwersalnego limitu ani sposobu zliczania dla interfejsów API śledzenia. Limity mogą być określane według konta, danych uwierzytelniających, punktu końcowego lub innego zakresu; stosuj rzeczywiste zasady dostawcy.

RFC 9110 określa dwie formy nagłówka Retry-After: nieujemną liczbę sekund lub datę HTTP. Analizuj obie. Jeśli wartością jest data, dokładnie oblicz pozostały czas oczekiwania i uwzględnij różnice zegarów. Jeśli wartość jest nieobecna lub nie można jej użyć, zastosuj skonfigurowaną awaryjną strategię czasu oczekiwania.

Samodzielne uśpienie jednego pracownika nie wystarczy, gdy inni pracownicy nadal korzystają z tego samego limitu. Umieść kontrolę szybkości na wspólnej granicy właściwej dla danych uwierzytelniających lub konta. Centralny harmonogram, współdzielony zasobnik tokenów lub równoważny rozproszony mechanizm kontroli może koordynować ten ruch.

1. Określ zakres, którego dotyczy problem. Ustal, którego punktu końcowego, danych uwierzytelniających lub konta dotyczy limit.
2. Przestrzegaj instrukcji oczekiwania serwera. Nie planuj ponowienia wcześniej, niż pozwala na to prawidłowa wartość Retry-After.
3. Opóźnij oczekujące zadania, których dotyczy problem. Unikaj blokowania niezależnego ruchu, gdy limity rzeczywiście są niezależne.
4. Zmniejsz współbieżność lub częstotliwość żądań. Jednorazowe oczekiwanie bez zmiany wzorca żądań może odtworzyć ten sam problem.
5. Wznawiaj pracę z odstępami. Po zakończeniu oczekiwania nie uwalniaj jednocześnie całego zaległego obciążenia.

Jeśli jest to obsługiwane, grupowanie może zmniejszyć liczbę żądań, ale musi uwzględniać udokumentowane zasady dotyczące rozmiaru partii i rozliczania. Nie zakładaj, że jedna partia zużywa jedną jednostkę limitu. Podobnie korzystaj z webhooków, gdy są dostępne, aby ograniczyć zbędne odpytywanie, zachowując jednocześnie wymagany przez integrację proces uzgadniania.

Stosuj ograniczone ponowienia z czasem oczekiwania i losowym opóźnieniem

Ponowienia są właściwe, gdy awaria może ustąpić bez zmiany żądania, a powtórzenie operacji jest bezpieczne. Tymczasowe awarie połączenia i wybrane błędy serwera mogą należeć do tej kategorii. Nieprawidłowy ładunek, dane uwierzytelniające lub trwały problem z uprawnieniami zwykle wymagają poprawy.

Praktycznym rozwiązaniem awaryjnym jest ograniczony wykładniczy czas oczekiwania z pełnym losowym opóźnieniem:

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)

W tym przypadku retry_index zaczyna się od zera dla pierwszego ponowienia, a brak wartości Retry-After nie dodaje żadnego minimalnego czasu oczekiwania. Są to wybory implementacyjne, a nie wymagany algorytm HTTP. Wybierz opóźnienie bazowe, limit, maksymalną liczbę prób i całkowity termin odpowiednie dla obciążenia oraz wytycznych dostawcy.

Losowe opóźnienie rozkłada żądania w czasie, zamiast powodować, że każdy pracownik powtarza je według tego samego harmonogramu. Limit opóźnienia ogranicza składnik wykładniczy; nie powinien zastępować dłuższego, prawidłowego czasu oczekiwania wymaganego przez serwer. Jeśli takie oczekiwanie przekracza termin zadania, odrocz lub zakończ zadanie zgodnie z zasadami, zamiast ponawiać próbę wcześniej.

Wyznacz granicę każdemu łańcuchowi ponowień

• Limit prób: ogranicz liczbę dodatkowych żądań.
• Limit czasu, który upłynął: zakończ ponawianie pracy, która przekroczyła użyteczne okno przetwarzania.
• Wyraźne przypisanie odpowiedzialności: wybierz warstwę kontrolującą ponowienia, aby ponowienia klienta HTTP i kolejki nie zwielokrotniały się nieoczekiwanie.
• Trwałe planowanie: przechowuj opóźnione zadania zamiast polegać na długim uśpieniu w krótkotrwałych procesach.
• Ścieżka odzyskiwania: wysyłaj zadania, dla których wyczerpano próby, do możliwej do przejrzenia kolejki nieudanych zadań wraz z powodem i kolejnym działaniem.

Podczas długotrwałej awarii rozważ wyłącznik awaryjny, który tymczasowo wstrzymuje rutynowe wywołania i zezwala na kontrolowane próby odzyskiwania. Jest to wzorzec odporności aplikacji, a nie dowód, że wymaga go konkretny dostawca śledzenia.

Rozstrzygaj niejednoznaczne operacje zapisu przed ich ponowieniem

Przekroczenie limitu czasu oznacza, że aplikacja nie otrzymała kompletnej odpowiedzi. Nie dowodzi, że serwer odrzucił żądanie lub nigdy go nie przetworzył. To rozróżnienie ma znaczenie podczas rejestrowania numerów śledzenia lub zmiany konfiguracji śledzenia.

RFC 9110 wyjaśnia metody idempotentne i przestrzega przed automatycznym ponawianiem żądań nieidempotentnych bez podstaw do stwierdzenia, że powtórzenie jest bezpieczne lub że pierwotna operacja nie została zastosowana. Oceniaj udokumentowaną semantykę operacji, zamiast zakładać, że każdy punkt końcowy śledzenia działa jak wyszukiwanie tylko do odczytu.

• Korzystaj z udokumentowanego przez dostawcę mechanizmu idempotencji, jeśli jest dostępny, przestrzegając zasad jego zakresu i przechowywania.
• Zachowuj ten sam klucz idempotencji dla ponowień tej samej operacji logicznej; nie zakładaj, że zostanie uwzględniony dowolny niestandardowy nagłówek.
• Jeśli jest to obsługiwane, sprawdź istniejącą rejestrację przed powtórzeniem niejednoznacznej operacji zapisu.
• Używaj lokalnego ograniczenia unikalności zgodnego z udokumentowaną tożsamością przesyłki u dostawcy.
• Przechowuj wynik operacji, aby ponowne dostarczenie z kolejki nie uruchamiało automatycznie kolejnego zapisu.

W przypadku operacji wsadowych zapisuj wynik każdego elementu. Ponawiaj tylko te elementy, które sklasyfikowano jako tymczasowo nieudane, a elementy o nieznanym wyniku poddawaj uzgodnieniu. Odtworzenie całej partii może powtórzyć pomyślnie wykonane działania i niepotrzebnie zużyć limit żądań.

Zastosuj zasady do swojego dostawcy śledzenia

W przypadku integracji z 17TRACK wykorzystaj stronę Tracking API oraz oficjalną dokumentację API jako punkty wyjścia do ustalenia umowy właściwej dla dostawcy. Utrzymuj możliwość konfiguracji klasyfikatora błędów, zamiast sztywno kodować założenia z ogólnego przewodnika HTTP.

Przed implementacją potwierdź schemat żądania właściwego punktu końcowego, kopertę odpowiedzi, znaczenie błędów na poziomie elementów, zakres limitu szybkości, ograniczenia partii oraz zasady dotyczące zduplikowanych zgłoszeń. Jeśli korzystasz z dostarczania zdarzeń, sprawdź także wymagania dotyczące potwierdzania, uwierzytelniania i ponownego dostarczania. Niniejszy przewodnik nie określa liczbowego limitu szybkości 17TRACK, harmonogramu ponowień ani funkcji idempotencji.

Zapisz każdą potwierdzoną regułę w mapowaniu od odpowiedzi dostawcy do działania aplikacji: popraw dane wejściowe, napraw konfigurację, zaczekaj, uzgodnij lub eskaluj. Nierozpoznany błąd powinien zachować kontekst diagnostyczny i podążać ograniczoną ścieżką awaryjną, a nie domyślnie uruchamiać nieograniczone ponowienia.

Monitoruj jakość odzyskiwania i testuj ścieżki awarii

Rejestruj operację, punkt końcowy, status HTTP, kod błędu aplikacji, numer próby, opóźnienie, następne zaplanowane działanie oraz identyfikator żądania dostawcy, jeśli został przekazany. Unikaj zapisywania kluczy API, zbędnych informacji adresowych lub nieograniczonych treści odpowiedzi. Maskuj lub haszuj identyfikatory śledzenia, gdy pełne wartości nie są potrzebne.

Śledź oddzielnie wskaźniki nieprawidłowych danych wejściowych, ograniczanie szybkości, wiek kolejki, wyczerpane ponowienia i ostatnią pomyślną synchronizację. Integracja może mieć niski wskaźnik błędów HTTP, a mimo to prezentować nieaktualne informacje o przesyłce. Strony przeznaczone dla klientów powinny zachowywać ostatni znany status przesyłki i odróżniać nieudaną aktualizację od wyjątku dostawy zgłoszonego przez przewoźnika.

Przed wydaniem przetestuj nieprawidłowe dane wejściowe, prawidłowe identyfikatory bez zdarzeń, obie formy Retry-After, brakujące nagłówki, częściowe awarie partii, przekroczenia limitu czasu po zapisach oraz ponowne dostarczanie z kolejki. Zasymuluj także awarię trwającą wystarczająco długo, aby wyczerpać budżet ponowień. Test kończy się powodzeniem tylko wtedy, gdy praca zatrzymuje się lub jest przewidywalnie odraczana, pomyślne elementy nie są niepotrzebnie odtwarzane, a nieudane elementy pozostają możliwe do odzyskania.

FAQ

Czy nieprawidłowy numer śledzenia należy automatycznie ponawiać?

Nie, jeśli interfejs API wyraźnie odrzuca dane wejściowe jako nieprawidłowe. Najpierw popraw numer, wybór przewoźnika lub wymagane pola. Jeśli odpowiedź oznacza natomiast, że zdarzenia przesyłki nie są jeszcze dostępne, użyj udokumentowanego procesu odświeżania, zamiast traktować to jako błąd walidacji.

Czy HTTP 200 oznacza, że żądanie wsadowe zakończyło się pełnym powodzeniem?

Niekoniecznie. Sprawdź schemat odpowiedzi dostawcy pod kątem wyników na poziomie operacji i poszczególnych elementów. Zapisuj pomyślne wyniki i odseparuj błędy, aby ponowienie jednego elementu nie powtarzało niepotrzebnie pozostałych.

Ile prób ponowienia powinna dopuszczać integracja śledzenia?

Nie ma uniwersalnej liczby. Ustal zarówno limit prób, jak i budżet czasu, opierając się na wytycznych dostawcy, bezpieczeństwie operacji oraz tym, jak długo wynik pozostaje użyteczny. Zaplanowana synchronizacja w tle może tolerować inne okno odzyskiwania niż interaktywne żądanie klienta.

Czy przekroczenie limitu czasu powinno natychmiast oznaczać awarię przesyłki?

Nie. Przekroczenie limitu czasu żądania jest wynikiem integracji, a nie zdarzeniem dotyczącym przesyłki. Zachowaj ostatni znany stan śledzenia, zaplanuj bezpieczne odzyskiwanie i nie przekształcaj problemu z łącznością w powiadomienie o nieudanej dostawie.

Co powinno się stać po wyczerpaniu ponowień?

Przenieś zadanie do trwałej kolejki nieudanych lub wymagających przeglądu zadań wraz z kontekstem diagnostycznym. Określ, czy odzyskanie wymaga poprawionych danych wejściowych, przywróconych danych uwierzytelniających, pomocy dostawcy czy późniejszego kontrolowanego odtworzenia. Nie odrzucaj go po cichu ani nie uruchamiaj ponownie tego samego nieograniczonego cyklu ponowień.

Źródła

• RFC 9110: Semantyka HTTP — semantyka statusów HTTP, metody idempotentne, zasady automatycznego ponawiania oraz pole Retry-After.
• RFC 6585: Dodatkowe kody statusu HTTP — definicja 429 Too Many Requests i opcjonalnego nagłówka Retry-After.
• 17TRACK Tracking API — oficjalny punkt wejścia do produktu API śledzenia.
• Dokumentacja API 17TRACK — materiały referencyjne do sprawdzania wymagań integracyjnych właściwych dla dostawcy.