Zpracování chyb v API pro sledování: Jak spravovat neplatná sledovací čísla, limity požadavků a opakované pokusy

Chyby API pro sledování zásilek řešte oddělením neplatných vstupů, dočasných selhání, překročení limitů a výsledků stavu zásilky. Neplatná sledovací čísla odmítněte nebo opravte, místo abyste je opakovaně odesílali beze změny, při omezení rychlosti koordinujte objem požadavků a dočasná selhání opakujte s omezeným exponenciálním odkladem a náhodným rozptylem. Před opakováním registračního nebo jiného zápisového požadavku zjistěte, zda první pokus uspěl.

Pro vývojáře, kteří připojují data o sledování k systému správy objednávek, skladové platformě nebo stránce se sledováním pro zákazníky, není cílem pouze méně neúspěšných požadavků. Cílem je spolehlivý přehled o zásilkách bez duplicitních registrací, lavin opakovaných pokusů, zavádějících zpráv o doručení nebo zbytečných požadavků na podporu.

Před volbou reakce klasifikujte selhání

Integrace sledování má několik samostatných výsledků, které je třeba vyhodnotit: zda byl síťový požadavek dokončen, zda API operaci přijalo, zda každá požadovaná položka sledování uspěla a zda jsou k dispozici události zásilky. Pokud všechny čtyři výsledky považujete za jediný příznak úspěchu či selhání, vznikají zbytečné chyby.

Úspěšná odpověď HTTP nemusí znamenat, že uspěla každá položka v dávce. Naopak úspěšně zpracované vyhledání bez událostí sledování nemusí být selháním API. Prohlédněte tělo odpovědi a použijte význam každého výsledku zdokumentovaný poskytovatelem.

Podmínka	Doporučená akce	Opakovat beze změny?
Poškozené číslo nebo neplatné pole požadavku	Ověřte a opravte vstup	Ne
Chybějící nebo neplatné přihlašovací údaje	Zkontrolujte přihlašovací údaje, oprávnění a prostředí	Až po opravě
Odpověď o omezení rychlosti	Odložte dotčenou práci a snižte společné zatížení požadavky	Po požadovaném čekání, pokud je to bezpečné
Dočasné selhání služby	Použijte omezený odklad a ověřte bezpečnost operace	Obvykle ano, v rámci rozpočtu opakování
Časový limit po odeslání registrace	Ověřte, zda registrace existuje	Ne slepě
Přijaté vyhledání bez událostí zásilky	Postupujte podle zdokumentovaného životního cyklu sledování	Použijte plánované obnovování, ne rychlé opakování

Stavové kódy HTTP jsou výchozím bodem, nikoli úplným rozhodovacím stromem specifickým pro poskytovatele. RFC 9110 definuje sémantiku HTTP, zatímco RFC 6585 definuje 429 Too Many Requests. Vaše integrace by měla také interpretovat zdokumentované aplikační chybové kódy a výsledky na úrovni položek.

Neplatná sledovací čísla: rozlišujte chybný vstup od chybějících událostí

„Neplatné sledovací číslo“ může označovat různé problémy: poškozený identifikátor, nepodporovanou kombinaci dopravce a čísla, chybějící povinné pole dopravce nebo jiné selhání ověření specifické pro poskytovatele. Nepředpokládejte, že číslo je neplatné jen proto, že nejsou vráceny žádné události sledování.

Ověřujte bez poškození identifikátoru

• Ukládejte sledovací čísla jako řetězce. Uložení jako čísla může odstranit počáteční nuly nebo změnit dlouhé identifikátory.
• Uchovávejte původní vstup. Udržujte samostatnou normalizovanou hodnotu, aby bylo možné změny zpětně kontrolovat.
• Normalizujte konzervativně. Je-li to vhodné, odstraňte okolní mezery, ale vnitřní znaky odstraňujte nebo měňte velikost písmen pouze tehdy, pokud to dovolují zdokumentovaná pravidla.
• Lokálně kontrolujte povinná pole. Před odesláním zachyťte prázdná čísla, chybějící identifikátory dopravce a neplatné struktury požadavků.
• Vyhněte se univerzálnímu regulárnímu výrazu pro sledovací čísla. Pravidlo navržené pro jednoho dopravce může odmítnout platné identifikátory jiného dopravce.
• Ověřte, co pole obsahuje. Číslo objednávky, skladová reference a sledovací číslo dopravce nejsou zaměnitelné, pokud je koncový bod výslovně nepodporuje.

Pokud API vstup výslovně odmítne, přesměrujte jej k opravě namísto automatické smyčky opakování. Uveďte užitečný důvod, například „je vyžadován identifikátor dopravce“, místo abyste každý problém ověření označili pouze jako „sledování selhalo“.

Stav „bez událostí“ považujte za samostatný

Zásilka může mít sledovací identifikátor ještě předtím, než budou k dispozici užitečné události pohybu. Správná reakce závisí na zdokumentovaném stavovém modelu API a kontextu zásilky. Ověřte, zda identifikátor pochází z přepravního systému, zda je výběr dopravce správný a zda odpověď označuje čekající data, nikoli odmítnutý vstup.

Používejte odlišné interní stavy, například input_rejected, awaiting_events a temporarily_unavailable. Jde o navrhované aplikační stavy, nikoli standardizované hodnoty API. Pomáhají zabránit tomu, aby se dočasná mezera v datech změnila v nepřesnou zprávu pro zákazníka.

Limity rychlosti spravujte napříč integrací, nikoli podle jednotlivých workerů

RFC 6585 definuje HTTP 429 jako odpověď o omezení rychlosti a umožňuje, aby obsahovala hlavičku Retry-After. Standard nestanovuje univerzální limit ani způsob počítání pro API sledování. Limity mohou být zdokumentovány podle účtu, přihlašovacích údajů, koncového bodu nebo jiného rozsahu; používejte skutečná pravidla poskytovatele.

RFC 9110 určuje pro Retry-After dvě formy: nezáporný počet sekund nebo datum HTTP. Zpracujte obě. Pokud je hodnotou datum, pečlivě vypočítejte zbývající čekání a zohledněte rozdíly hodin. Pokud hodnota chybí nebo ji nelze použít, uplatněte nakonfigurovanou záložní politiku odkladu.

Nestačí, aby jeden worker spal, pokud ostatní workeři nadále využívají stejný limit. Řízení rychlosti umístěte na sdílenou hranici pro příslušné přihlašovací údaje nebo účet. Centrální plánovač, sdílený token bucket nebo rovnocenné distribuované řízení může tento provoz koordinovat.

1. Určete dotčený rozsah. Zjistěte, na který koncový bod, přihlašovací údaje nebo účet se limit vztahuje.
2. Respektujte pokyn serveru k čekání. Neplánujte opakování dříve, než dovoluje platná hodnota Retry-After.
3. Odložte dotčenou práci ve frontě. Neomezujte nesouvisející provoz, pokud jsou limity skutečně nezávislé.
4. Snižte souběžnost nebo frekvenci požadavků. Jednorázové čekání bez změny vzorce požadavků může stejný problém znovu vyvolat.
5. Obnovte provoz s rozestupy. Po skončení čekání neuvolňujte celou frontu současně.

Pokud je podporováno dávkové zpracování, může snížit počet požadavků, musí však respektovat zdokumentovaná pravidla velikosti dávek a účtování. Nepředpokládejte, že jedna dávka spotřebuje jednu jednotku limitu. Stejně tak používejte webhooky, jsou-li k dispozici, ke snížení zbytečného dotazování, přičemž zachovejte proces rekonciliace vyžadovaný integrací.

Používejte omezené opakování s odkladem a náhodným rozptylem

Opakování je vhodné, když může selhání zmizet bez změny požadavku a opakování operace je bezpečné. Do této kategorie mohou patřit dočasná selhání připojení a vybrané chyby serveru. Poškozený obsah, neplatné přihlašovací údaje nebo trvalý problém s oprávněními obvykle vyžadují opravu.

Praktickou záložní možností je omezený exponenciální odklad s úplným náhodným rozptylem:

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)

Zde retry_index začíná při prvním opakování nulou a chybějící Retry-After nepřidává žádnou další minimální dobu čekání. Jde o implementační volby, nikoli o povinný algoritmus HTTP. Zvolte základní prodlevu, maximum, limit pokusů a celkový termín podle svého zatížení a pokynů poskytovatele.

Náhodný rozptyl rozloží požadavky v čase, místo aby je každý worker opakoval podle stejného rozvrhu. Limit prodlevy omezuje exponenciální složku; neměl by přepsat delší platné čekání požadované serverem. Pokud toto čekání překročí termín úlohy, odložte nebo ukončete úlohu podle zásad namísto předčasného opakování.

Každému řetězci opakování stanovte konec

• Limit pokusů: omezte počet dalších požadavků.
• Limit uplynulého času: přestaňte opakovat práci, která překročila své užitečné časové okno.
• Jasné vlastnictví: určete vrstvu, která řídí opakování, aby se opakování HTTP klienta a fronty neočekávaně nenásobilo.
• Trvalé plánování: ukládejte odložené úlohy namísto spoléhání na dlouhé spánky v krátce žijících procesech.
• Cesta obnovy: vyčerpané úlohy odešlete do kontrolovatelné fronty neúspěšných úloh s uvedením důvodu a další akce.

Během déletrvajícího výpadku zvažte jistič, který dočasně pozastaví běžná volání a povolí řízené testy obnovy. Jde o vzor odolnosti aplikace, nikoli o důkaz, že jej vyžaduje konkrétní poskytovatel sledování.

Nejednoznačné zápisy vyřešte před jejich opětovným odesláním

Časový limit znamená, že vaše aplikace neobdržela úplnou odpověď. Neprokazuje, že server požadavek odmítl nebo nikdy nezpracoval. Tento rozdíl je důležitý při registraci sledovacích čísel nebo změně konfigurace sledování.

RFC 9110 vysvětluje idempotentní metody a varuje před automatickým opakováním neidempotentních požadavků bez důvodu domnívat se, že je opakování bezpečné nebo že původní operace nebyla provedena. Vyhodnoťte zdokumentovanou sémantiku operace a nepředpokládejte, že každý koncový bod sledování funguje jako vyhledávání pouze pro čtení.

• Je-li k dispozici mechanismus idempotence zdokumentovaný poskytovatelem, používejte jej podle jeho rozsahu a pravidel uchovávání.
• Pro opakování stejné logické operace zachovejte stejný idempotency key; nepředpokládejte, že bude respektována libovolná vlastní hlavička.
• Je-li to podporováno, před opakováním nejednoznačného zápisu zkontrolujte existující registraci.
• Použijte lokální omezení jedinečnosti odpovídající zdokumentované identitě zásilky u poskytovatele.
• Ukládejte výsledek operace, aby opětovné doručení z fronty automaticky nespustilo další zápis.

U dávkových operací ukládejte výsledek každé položky. Opakujte pouze položky klasifikované jako dočasně neúspěšné a rekoncilujte položky s neznámým výsledkem. Opětovné odeslání celé dávky může zopakovat úspěšnou práci a zbytečně spotřebovat limit požadavků.

Použijte zásady pro svého poskytovatele sledování

Pro integraci 17TRACK použijte stránku Tracking API a oficiální dokumentaci API jako výchozí body pro smlouvu specifickou pro poskytovatele. Klasifikátor chyb udržujte konfigurovatelný namísto pevného zakódování předpokladů z obecné příručky HTTP.

Před implementací ověřte schéma požadavku příslušného koncového bodu, obálku odpovědi, významy chyb na úrovni položek, rozsah omezení rychlosti, omezení dávek a pravidla pro duplicitní odeslání. Pokud používáte doručování událostí, ověřte také požadavky na potvrzení, ověřování a opětovné doručení. Tato příručka nepředepisuje číselný limit rychlosti 17TRACK, rozvrh opakování ani funkci idempotence.

Každé potvrzené pravidlo zaznamenejte do mapování od odpovědi poskytovatele k akci aplikace: opravit vstup, opravit konfiguraci, počkat, rekoncilovat nebo eskalovat. Nerozpoznaná chyba by měla zachovat diagnostický kontext a následovat omezenou záložní cestu, nikoli automaticky vést k neomezenému opakování.

Sledujte kvalitu obnovy a testujte chybové scénáře

Zaznamenávejte operaci, koncový bod, stav HTTP, aplikační chybový kód, číslo pokusu, latenci, další naplánovanou akci a identifikátor požadavku poskytovatele, pokud je k dispozici. Nezaznamenávejte klíče API, nepotřebné informace o adrese ani neomezená těla odpovědí. Pokud nejsou úplné hodnoty potřeba, sledovací identifikátory maskujte nebo hašujte.

Samostatně sledujte míru neplatných vstupů, omezení rychlosti, stáří fronty, vyčerpaná opakování a poslední úspěšnou synchronizaci. Integrace může mít nízkou míru chyb HTTP a přesto poskytovat zastaralé informace o zásilce. Stránky pro zákazníky by měly zachovat poslední známý stav zásilky a rozlišovat selhání obnovení od výjimky doručení nahlášené dopravcem.

Před vydáním otestujte poškozený vstup, platné identifikátory bez událostí, obě formy Retry-After, chybějící hlavičky, částečná selhání dávek, časové limity po zápisech a opětovné doručení z fronty. Simulujte také dostatečně dlouhý výpadek, aby se vyčerpal rozpočet opakování. Test je úspěšný pouze tehdy, když se práce předvídatelně zastaví nebo odloží, úspěšné položky se zbytečně neopakují a neúspěšné položky zůstanou obnovitelné.

Časté dotazy

Má se neplatné sledovací číslo automaticky opakovat?

Ne, pokud API vstup výslovně odmítne jako neplatný. Nejprve opravte číslo, výběr dopravce nebo povinná pole. Pokud odpověď místo toho znamená, že události zásilky ještě nejsou k dispozici, použijte zdokumentovaný postup obnovování a nepovažujte ji za selhání ověření.

Znamená HTTP 200, že dávkový požadavek zcela uspěl?

Ne nutně. Zkontrolujte schéma odpovědi poskytovatele pro výsledky na úrovni operace i položky. Úspěchy ukládejte a selhání izolujte, aby opakování jedné položky zbytečně neopakovalo ostatní.

Kolik pokusů o opakování by měla integrace sledování povolit?

Neexistuje univerzální počet. Stanovte limit pokusů i rozpočet uplynulého času podle pokynů poskytovatele, bezpečnosti operace a doby, po kterou zůstává výsledek užitečný. Plánovaná synchronizace na pozadí může snést jiné okno obnovy než interaktivní požadavek zákazníka.

Má časový limit okamžitě označit zásilku jako neúspěšnou?

Ne. Časový limit požadavku je výsledek integrace, nikoli událost zásilky. Zachovejte poslední známý stav sledování, naplánujte bezpečnou obnovu a nepřevádějte problém s připojením na oznámení o selhání doručení.

Co se má stát po vyčerpání opakování?

Přesuňte úlohu do trvalé fronty neúspěšných úloh nebo kontrolní fronty spolu s diagnostickým kontextem. Určete, zda obnova vyžaduje opravený vstup, obnovené přihlašovací údaje, pomoc poskytovatele nebo pozdější řízené opakování. Úlohu tiše nezahazujte ani znovu nespouštějte stejný neomezený cyklus opakování.

Zdroje

• RFC 9110: HTTP Semantics — sémantika stavů HTTP, idempotentní metody, úvahy o automatickém opakování a pole Retry-After.
• RFC 6585: Additional HTTP Status Codes — definice 429 Too Many Requests a jeho volitelné hlavičky Retry-After.
• 17TRACK Tracking API — oficiální vstupní bod pro produkt API sledování.
• 17TRACK API documentation — reference pro ověření integračních požadavků specifických pro poskytovatele.