DomovBlogRiešenie chýb v Tracking API: Ako spravovať neplatné sledovacie čísla, limity počtu požiadaviek a opakované pokusy

Riešenie chýb v Tracking API: Ako spravovať neplatné sledovacie čísla, limity počtu požiadaviek a opakované pokusy

17TRACK

Chyby rozhrania API na sledovanie zásielok spracúvajte oddelením neplatných vstupov, dočasných zlyhaní, limitov požiadaviek a výsledkov stavu zásielky. Neplatné čísla zásielok odmietnite alebo opravte namiesto ich opakovania bez zmien, pri obmedzení rýchlosti koordinujte objem požiadaviek a dočasné zlyhania opakujte s obmedzeným exponenciálnym oneskorením a náhodným rozptylom. Pred opakovaním registrácie alebo inej požiadavky na zápis zistite, či bol prvý pokus úspešný.

Spracovanie chýb API na sledovanie zásielok: Ako spravovať neplatné čísla zásielok

Pre vývojárov, ktorí pripájajú údaje o sledovaní k systému správy objednávok, skladovej platforme alebo stránke sledovania určenej zákazníkom, cieľom nie je iba menej neúspešných požiadaviek. Ide o spoľahlivý prehľad o zásielkach bez duplicitných registrácií, lavín opakovaných pokusov, zavádzajúcich správ o doručení alebo zbytočných požiadaviek na podporu.

Pred výberom reakcie klasifikujte zlyhanie

Integrácia sledovania má niekoľko samostatných výsledkov, ktoré treba vyhodnotiť: či bola sieťová požiadavka dokončená, či rozhranie API operáciu prijalo, či bola každá požadovaná položka sledovania úspešná a či sú k dispozícii udalosti zásielky. Zaobchádzanie so všetkými štyrmi ako s jedným príznakom úspechu alebo zlyhania vytvára chybám, ktorým sa dá predísť.

Úspešná odpoveď HTTP nemusí znamenať, že každá položka v dávke bola úspešná. Naopak, úspešne spracované vyhľadanie bez udalostí sledovania nemusí byť zlyhaním API. Skontrolujte telo odpovede a použite zdokumentovaný význam poskytovateľa pre každý výsledok.

PodmienkaOdporúčaná akciaOpakovať bez zmien?
Nesprávne naformátované číslo alebo neplatné pole požiadavkyOveriť a opraviť vstupNie
Chýbajúce alebo neplatné prihlasovacie údajeSkontrolovať prihlasovacie údaje, oprávnenia a prostredieAž po oprave
Odpoveď o prekročení limitu požiadaviekOdložiť ovplyvnenú prácu a znížiť spoločné zaťaženie požiadavkamiPo požadovanom čakaní, ak je to bezpečné
Dočasné zlyhanie službyPoužiť obmedzené oneskorenie a overiť bezpečnosť operácieZvyčajne áno, v rámci rozpočtu opakovaní
Časový limit po odoslaní registrácieOveriť, či registrácia existujeNie naslepo
Prijaté vyhľadanie bez udalostí zásielkyPostupovať podľa zdokumentovaného životného cyklu sledovaniaPoužiť plánované obnovenie, nie rýchle opakovanie

Stavové kódy HTTP poskytujú východisko, nie úplný rozhodovací strom špecifický pre poskytovateľa. RFC 9110 definuje sémantiku HTTP, zatiaľ čo RFC 6585 definuje 429 Too Many Requests. Vaša integrácia by mala interpretovať aj zdokumentované aplikačné chybové kódy a výsledky na úrovni položiek.

Neplatné čísla zásielok: rozlišujte nesprávny vstup od chýbajúcich udalostí

„Neplatné číslo zásielky“ môže označovať rôzne problémy: nesprávne naformátovaný identifikátor, nepodporovanú kombináciu dopravcu a čísla, chýbajúce povinné pole dopravcu alebo inú validačnú chybu špecifickú pre poskytovateľa. Nepredpokladajte, že číslo je neplatné len preto, že sa nevrátili žiadne udalosti sledovania.

Overujte bez poškodenia identifikátora

  • Čísla zásielok ukladajte ako reťazce. Číselné uloženie môže odstrániť úvodné nuly alebo zmeniť dlhé identifikátory.
  • Zachovajte pôvodný vstup. Uchovávajte samostatnú normalizovanú hodnotu, aby bolo možné zmeny spätne kontrolovať.
  • Normalizujte konzervatívne. V prípade potreby odstráňte okolité medzery, ale vnútorné znaky odstraňujte alebo meniť veľkosť písmen len vtedy, keď to povoľujú zdokumentované pravidlá.
  • Lokálne kontrolujte povinné polia. Pred odoslaním zachyťte prázdne čísla, chýbajúce identifikátory dopravcu a neplatnú štruktúru požiadavky.
  • Vyhnite sa univerzálnemu regulárnemu výrazu pre čísla zásielok. Pravidlo vytvorené pre jedného dopravcu môže odmietnuť platné identifikátory iného dopravcu.
  • Overte, čo pole obsahuje. Číslo objednávky, referencia skladu a sledovacie číslo dopravcu nie sú vzájomne zameniteľné, pokiaľ ich koncový bod výslovne nepodporuje.

Ak API vstup výslovne odmietne, presmerujte ho na opravu namiesto automatickej slučky opakovania. Uveďte užitočný dôvod, napríklad „vyžaduje sa identifikátor dopravcu“, namiesto zjednodušenia každého problému s validáciou na „sledovanie zlyhalo“.

„Žiadne udalosti“ považujte za samostatný stav

Zásielka môže mať identifikátor sledovania ešte predtým, než budú k dispozícii užitočné udalosti pohybu. Správna reakcia závisí od zdokumentovaného modelu stavov API a kontextu zásielky. Skontrolujte, či identifikátor pochádza zo systému prepravy, či je výber dopravcu správny a či odpoveď signalizuje čakajúce údaje, a nie odmietnutý vstup.

Používajte odlišné interné stavy, napríklad input_rejected, awaiting_events a temporarily_unavailable. Ide o navrhované stavy aplikácie, nie o štandardizované hodnoty API. Pomáhajú zabrániť tomu, aby sa dočasná medzera v údajoch zmenila na nepresnú správu pre zákazníka.

Limity požiadaviek spravujte v rámci celej integrácie, nie podľa pracovníka

RFC 6585 definuje HTTP 429 ako odpoveď na obmedzenie rýchlosti a umožňuje, aby obsahovala hlavičku Retry-After. Norma nestanovuje univerzálny limit ani spôsob počítania pre API na sledovanie zásielok. Limity môžu byť zdokumentované podľa účtu, prihlasovacích údajov, koncového bodu alebo iného rozsahu; používajte skutočné pravidlá poskytovateľa.

RFC 9110 špecifikuje dve formy Retry-After: nezáporný počet sekúnd alebo dátum HTTP. Spracujte obe. Ak je hodnotou dátum, opatrne vypočítajte zostávajúce čakanie a zohľadnite rozdiely v hodinách. Ak hodnota chýba alebo je nepoužiteľná, použite nakonfigurovanú záložnú politiku oneskorenia.

Keď jeden pracovník čaká samostatne, nestačí to, ak ostatní pracovníci naďalej využívajú rovnaký limit. Riadenie rýchlosti umiestnite na spoločnú hranicu príslušných prihlasovacích údajov alebo účtu. Centrálny plánovač, spoločný tokenový vedierko alebo ekvivalentné distribuované riadenie môže túto prevádzku koordinovať.

  1. Identifikujte ovplyvnený rozsah. Určite, na ktorý koncový bod, prihlasovacie údaje alebo účet sa limit vzťahuje.
  2. Rešpektujte pokyn servera na čakanie. Neplánujte skoršie opakovanie, než povoľuje platná hodnota Retry-After.
  3. Odložte ovplyvnenú prácu vo fronte. Neblokujte nesúvisiacu prevádzku, ak sú limity skutočne nezávislé.
  4. Znížte súbežnosť alebo frekvenciu požiadaviek. Jednorazové čakanie bez zmeny vzoru požiadaviek môže rovnaký problém zopakovať.
  5. Obnovte prevádzku s rozostupmi. Po skončení čakania neuvoľňujte celý backlog naraz.

Ak je to podporované, dávkové spracovanie môže znížiť počet požiadaviek, musí však rešpektovať zdokumentované pravidlá veľkosti dávky a účtovania. Nepredpokladajte, že jedna dávka spotrebuje jednu jednotku limitu. Rovnako používajte webhooky, ak sú k dispozícii, aby ste znížili zbytočné dotazovanie, pričom zachovajte proces zosúladenia vyžadovaný vašou integráciou.

Používajte obmedzené opakovanie s oneskorením a náhodným rozptylom

Opakovanie je vhodné vtedy, keď môže zlyhanie pominúť bez zmeny požiadavky a opakovanie operácie je bezpečné. Do tejto kategórie môžu patriť dočasné zlyhania pripojenia a vybrané chyby servera. Nesprávne vytvorený obsah, neplatné prihlasovacie údaje alebo trvalý problém s oprávneniami si vo všeobecnosti vyžadujú opravu.

Praktickou záložnou možnosťou je ohraničené exponenciálne oneskorenie s úplným náhodným rozptylom:

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)

Tu sa retry_index začína pri nule pre prvé opakovanie a chýbajúca hodnota Retry-After nepridáva žiadne ďalšie minimálne čakanie. Ide o implementačné voľby, nie o povinný algoritmus HTTP. Základné oneskorenie, horný limit, počet pokusov a celkový termín zvoľte podľa svojho pracovného zaťaženia a pokynov poskytovateľa.

Náhodný rozptyl rozkladá požiadavky v čase namiesto toho, aby ich každý pracovník opakoval podľa rovnakého harmonogramu. Horný limit oneskorenia obmedzuje exponenciálnu zložku; nemal by prepisovať dlhšie platné čakanie požadované serverom. Ak toto čakanie prekročí termín úlohy, odložte alebo ukončite úlohu podľa pravidiel namiesto skorého opakovania.

Každému reťazcu opakovaní stanovte koniec

  • Limit pokusov: ohraničte počet ďalších požiadaviek.
  • Limit uplynutého času: prestaňte opakovať prácu, ktorá prekročila svoje užitočné časové okno spracovania.
  • Jednoznačné vlastníctvo: určte, ktorá vrstva riadi opakovania, aby sa opakovania HTTP klienta a frontu neočakávane nenásobili.
  • Trvalé plánovanie: ukladajte odložené úlohy namiesto spoliehania sa na dlhé čakanie v krátkodobo žijúcich procesoch.
  • Cesta obnovy: odosielajte úlohy po vyčerpaní pokusov do kontrolovateľného frontu neúspešných úloh s dôvodom a ďalšou akciou.

Počas dlhodobého výpadku zvážte istič, ktorý dočasne pozastaví bežné volania a povolí riadené overovacie pokusy obnovy. Ide o vzor odolnosti aplikácie, nie o dôkaz, že ho vyžaduje konkrétny poskytovateľ sledovania.

Pred opätovným odoslaním vyriešte nejednoznačné zápisy

Časový limit znamená, že aplikácia nedostala úplnú odpoveď. Nedokazuje však, že server požiadavku odmietol alebo ju nikdy nespracoval. Tento rozdiel je dôležitý pri registrácii čísel zásielok alebo zmene konfigurácie sledovania.

RFC 9110 vysvetľuje idempotentné metódy a varuje pred automatickým opakovaním neidempotentných požiadaviek bez dôvodu domnievať sa, že opakovanie je bezpečné alebo že pôvodná operácia nebola vykonaná. Vyhodnoťte zdokumentovanú sémantiku operácie namiesto predpokladu, že každý koncový bod sledovania funguje ako vyhľadávanie iba na čítanie.

  • Ak je k dispozícii mechanizmus idempotencie zdokumentovaný poskytovateľom, používajte ho podľa jeho rozsahu a pravidiel uchovávania.
  • Pri opakovaniach tej istej logickej operácie používajte rovnaký idempotentný kľúč; nepredpokladajte, že ľubovoľná vlastná hlavička bude akceptovaná.
  • Ak je to podporované, pred opakovaním nejednoznačného zápisu skontrolujte existujúcu registráciu.
  • Použite lokálne obmedzenie jedinečnosti zosúladené so zdokumentovanou identitou zásielky poskytovateľa.
  • Uložte výsledok operácie, aby opätovné doručenie z frontu automaticky nespustilo ďalší zápis.

Pri dávkových operáciách trvalo ukladajte výsledok každej položky. Opakujte iba položky klasifikované ako dočasne neúspešné a zosúlaďte položky, ktorých výsledok zostáva neznámy. Opätovné prehratie celej dávky môže zopakovať úspešnú prácu a zbytočne spotrebovať limit požiadaviek.

Uplatnite pravidlá na svojho poskytovateľa sledovania

Pri integrácii 17TRACK použite stránku Tracking API a oficiálnu dokumentáciu API ako východisko pre zmluvu špecifickú pre poskytovateľa. Klasifikátor chýb udržujte konfigurovateľný namiesto pevného zakódovania predpokladov z všeobecnej príručky HTTP.

Pred implementáciou potvrďte schému požiadavky príslušného koncového bodu, obálku odpovede, význam chýb na úrovni položiek, rozsah limitu požiadaviek, obmedzenia dávok a pravidlá duplicitných odoslaní. Ak používate doručovanie udalostí, overte aj požiadavky na potvrdenie prijatia, autentifikáciu a opätovné doručenie. Táto príručka neurčuje číselný limit 17TRACK, harmonogram opakovaní ani funkciu idempotencie.

Každé potvrdené pravidlo zaznamenajte do mapovania od odpovede poskytovateľa k akcii aplikácie: opraviť vstup, opraviť konfiguráciu, počkať, zosúladiť alebo eskalovať. Nerozpoznaná chyba by mala zachovať diagnostický kontext a prejsť obmedzenou záložnou cestou, nie automaticky viesť k neobmedzenému opakovaniu.

Sledujte kvalitu obnovy a testujte cesty zlyhania

Zaznamenávajte operáciu, koncový bod, stav HTTP, aplikačný chybový kód, číslo pokusu, latenciu, ďalšiu naplánovanú akciu a identifikátor požiadavky poskytovateľa, ak je uvedený. Vyhnite sa zaznamenávaniu kľúčov API, nepotrebných adresných údajov alebo neobmedzených tiel odpovedí. Identifikátory sledovania maskujte alebo hašujte tam, kde nie sú potrebné ich úplné hodnoty.

Samostatne sledujte mieru neplatných vstupov, obmedzovanie rýchlosti, vek položiek vo fronte, vyčerpané opakovania a poslednú úspešnú synchronizáciu. Integrácia môže mať nízku mieru chýb HTTP a zároveň poskytovať zastarané informácie o zásielkach. Stránky určené zákazníkom by mali zachovať posledný známy stav zásielky a rozlišovať zlyhanie obnovenia od výnimky doručenia nahlásenej dopravcom.

Pred vydaním otestujte nesprávne naformátovaný vstup, platné identifikátory bez udalostí, obe formy Retry-After, chýbajúce hlavičky, čiastočné zlyhania dávok, časové limity po zápisoch a opätovné doručenie z frontu. Simulujte aj dostatočne dlhý výpadok na vyčerpanie rozpočtu opakovaní. Test je úspešný iba vtedy, keď sa práca predvídateľne zastaví alebo odloží, úspešné položky sa zbytočne neprehrajú a neúspešné položky zostanú obnoviteľné.

Často kladené otázky

Má sa neplatné číslo zásielky automaticky opakovať?

Nie vtedy, keď API vstup výslovne odmietne ako neplatný. Najprv opravte číslo, výber dopravcu alebo povinné polia. Ak odpoveď namiesto toho znamená, že udalosti zásielky ešte nie sú k dispozícii, použite zdokumentovaný pracovný postup obnovenia a nepovažujte to za chybu validácie.

Znamená HTTP 200, že dávková požiadavka bola úplne úspešná?

Nie nevyhnutne. Skontrolujte schému odpovede poskytovateľa, či obsahuje výsledky na úrovni operácie aj položky. Úspechy trvalo ukladajte a zlyhania izolujte, aby opakovanie jednej položky zbytočne neopakovalo ostatné.

Koľko pokusov o opakovanie má integrácia sledovania povoliť?

Neexistuje univerzálny počet. Nastavte limit pokusov aj rozpočet uplynutého času podľa pokynov poskytovateľa, bezpečnosti operácie a dĺžky užitočnosti výsledku. Plánovaná synchronizácia na pozadí môže tolerovať iné okno obnovy než interaktívna požiadavka zákazníka.

Má časový limit okamžite označiť zásielku ako neúspešnú?

Nie. Časový limit požiadavky je výsledkom integrácie, nie udalosťou zásielky. Zachovajte posledný známy stav sledovania, naplánujte bezpečnú obnovu a nepremeňte problém s pripojením na oznámenie o zlyhaní doručenia.

Čo sa má stať po vyčerpaní opakovaní?

Presuňte úlohu do trvalého frontu neúspešných úloh alebo frontu na kontrolu spolu s diagnostickým kontextom. Určte, či obnova vyžaduje opravený vstup, obnovené prihlasovacie údaje, pomoc poskytovateľa alebo neskoršie riadené prehratie. Úlohu potichu nezahadzujte ani nereštartujte rovnaký neobmedzený cyklus opakovaní.

Zdroje

Loading