Tracking API -virheenkäsittely: Kuinka käsitellä virheellisiä seurantanumeroita, pyyntörajoituksia ja uudelleenyrityksiä

Käsittele seurantapalvelun API-virheitä erottamalla virheelliset syötteet, tilapäiset häiriöt, nopeusrajoitukset ja lähetyksen tilatulokset toisistaan. Hylkää virheelliset seurantanumerot tai korjaa ne sen sijaan, että yrittäisit uudelleen muuttamatta niitä, koordinoi pyyntöjen määrää rajoituksen aikana ja yritä tilapäisten häiriöiden jälkeen uudelleen rajoitetulla eksponentiaalisella viiveellä ja hajonnalla. Ennen kuin toistat rekisteröinnin tai muun kirjoituspyynnön, selvitä, onnistuiko ensimmäinen yritys.

Kehittäjille, jotka yhdistävät seurantatietoja tilaustenhallintajärjestelmään, varastoalustaan tai asiakkaille suunnatulle seurant-sivulle, tavoitteena ei ole ainoastaan vähentää epäonnistuneita pyyntöjä. Tavoitteena on luotettava lähetyksen näkyvyys ilman päällekkäisiä rekisteröintejä, uudelleenyritysten aiheuttamia ruuhkia, harhaanjohtavia toimitusviestejä tai tarpeettomia tukipyyntöjä.

Luokittele virhe ennen vastauksen valitsemista

Seurannan integraatiossa on useita erillisiä tuloksia arvioitavaksi: valmistuiko verkkopyyntö, hyväksyikö API toiminnon, onnistuiko kukin pyydetty seurantakohde ja ovatko lähetyksen tapahtumat saatavilla. Kaikkien neljän käsitteleminen yhtenä onnistumis- tai epäonnistumisilmaisimena aiheuttaa vältettävissä olevia virheitä.

HTTP-onnistumisvastaus ei välttämättä tarkoita, että jokainen erän kohde onnistui. Vastaavasti onnistuneesti käsitelty haku, josta ei löydy seurantatapahtumia, ei välttämättä tarkoita API-virhettä. Tarkista vastausrungon sisältö ja sovella palveluntarjoajan dokumentoitua merkitystä kuhunkin tulokseen.

Ehto	Suositeltu toimenpide	Yritetäänkö uudelleen muuttamatta pyyntöä?
Virheellinen numero tai pyyntökenttä	Vahvista ja korjaa syöte	Ei
Puuttuvat tai virheelliset tunnistetiedot	Tarkista tunnistetiedot, käyttöoikeudet ja ympäristö	Ei ennen korjaamista
Nopeusrajoitusvastaus	Viivästytä kyseistä työtä ja vähennä jaettua pyyntökuormaa	Vaaditun odotuksen jälkeen, jos se on turvallista
Tilapäinen palveluhäiriö	Sovella rajoitettua backoff-viivettä ja tarkista toiminnon turvallisuus	Yleensä, uudelleenyritysbudjetin puitteissa
Aikakatkaisu rekisteröinnin lähettämisen jälkeen	Selvitä, onko rekisteröinti olemassa	Ei sokeasti
Hyväksytty haku ilman lähetyksen tapahtumia	Noudata dokumentoitua seurantaprosessia	Käytä ajastettua päivitystä, älä nopeita uudelleenyrityksiä

HTTP-tilakoodit ovat lähtökohta, eivät täydellinen palveluntarjoajakohtainen päätöspuu. RFC 9110 määrittelee HTTP-semanttiikan, kun taas RFC 6585 määrittelee 429 Too Many Requests -tilan. Integraation on myös tulkittava dokumentoidut sovellustason virhekoodit ja kohdetason tulokset.

Virheelliset seurantanumerot: erota virheellinen syöte puuttuvista tapahtumista

”Virheellinen seurantanumero” voi tarkoittaa eri ongelmia: virheellistä tunnistetta, palveluntarjoajan ja numeron tukematonta yhdistelmää, puuttuvaa pakollista kuljetusliikkeen kenttää tai muuta palveluntarjoajakohtaista vahvistusvirhettä. Älä oleta numeroa virheelliseksi vain siksi, ettei seurantatapahtumia palauteta.

Vahvista tunniste vahingoittamatta sitä

• Tallenna seurantanumerot merkkijonoina. Numeerinen tallennus voi poistaa alussa olevat nollat tai muuttaa pitkiä tunnisteita.
• Säilytä alkuperäinen syöte. Pidä normalisoitu arvo erillään, jotta muunnokset ovat jäljitettävissä.
• Normalisoi varovasti. Poista tarvittaessa ympäröivät välilyönnit, mutta poista sisäiset merkit tai muuta kirjainkokoa vain, jos dokumentoidut säännöt sallivat sen.
• Tarkista pakolliset kentät paikallisesti. Havaitse tyhjät numerot, puuttuvat kuljetusliikkeen tunnisteet ja virheelliset pyyntömuodot ennen niiden lähettämistä.
• Vältä yleispätevää seurantanumeron säännöllistä lauseketta. Yhdelle kuljetusliikkeelle suunniteltu sääntö voi hylätä toisen kelvolliset tunnisteet.
• Varmista kentän sisältö. Tilausnumero, varaston viite ja kuljetusliikkeen seurantanumero eivät ole keskenään vaihdettavia, ellei päätepiste nimenomaisesti tue niitä.

Jos API hylkää syötteen nimenomaisesti, ohjaa se korjattavaksi automaattisen uudelleenyrityssilmukan sijaan. Ilmoita hyödyllinen syy, kuten ”kuljetusliikkeen tunniste vaaditaan”, sen sijaan että kaikki vahvistusongelmat pelkistettäisiin muotoon ”seuranta epäonnistui”.

Käsittele ”ei tapahtumia” erillisenä tilana

Lähetyksellä voi olla seurannan tunniste ennen kuin hyödylliset liikkeen tapahtumat tulevat saataville. Oikea toiminta riippuu APIn dokumentoidusta tilamallista ja lähetyksen kontekstista. Tarkista, tuliko tunniste lähetysjärjestelmästä, onko kuljetusliikkeen valinta oikea ja ilmaiseeko vastaus odottavaa tietoa hylätyn syötteen sijaan.

Käytä erillisiä sisäisiä tiloja, kuten input_rejected, awaiting_events ja temporarily_unavailable. Nämä ovat ehdotettuja sovellustiloja, eivät standardoituja API-arvoja. Ne auttavat estämään tilapäisen tietokatkoksen muuttumisen epätarkaksi asiakasviestiksi.

Hallitse nopeusrajoituksia koko integraatiossa, ei työntekijäkohtaisesti

RFC 6585 määrittelee HTTP 429 -vastauksen nopeusrajoitukseksi ja sallii sen sisältää Retry-After-otsakkeen. Standardi ei määrittele yleistä seuranta-APIn sallittua määrää tai laskentatapaa. Rajoitukset voidaan dokumentoida tilin, tunnistetiedon, päätepisteen tai muun laajuuden mukaan; käytä palveluntarjoajan todellisia sääntöjä.

RFC 9110 määrittelee Retry-After-otsakkeelle kaksi muotoa: ei-negatiivisen sekuntimäärän tai HTTP-päivämäärän. Jäsennä molemmat. Jos arvo on päivämäärä, laske jäljellä oleva odotusaika huolellisesti ja huomioi kellojen erot. Jos arvo puuttuu tai sitä ei voida käyttää, sovella määritettyä varavaihtoehdon backoff-käytäntöä.

Yksittäisen työntekijän nukkuminen ei riitä, jos muut työntekijät jatkavat saman käyttökiintiön käyttämistä. Sijoita nopeudenhallinta kyseisen tunnistetiedon tai tilin jaettuun rajapintaan. Keskitetty ajastin, jaettu token bucket tai vastaava hajautettu ohjaus voi koordinoida liikennettä.

1. Tunnista vaikutuksen laajuus. Selvitä, mitä päätepistettä, tunnistetietoa tai tiliä rajoitus koskee.
2. Noudata palvelimen odotusohjetta. Älä ajoita uudelleenyritystä aikaisemmaksi kuin kelvollinen Retry-After-arvo sallii.
3. Viivästytä kyseistä jonotettua työtä. Vältä toisistaan riippumattoman liikenteen estämistä, kun rajoitukset ovat aidosti erillisiä.
4. Vähennä samanaikaisuutta tai pyyntötiheyttä. Yksi odotus ilman pyyntömallin muuttamista voi aiheuttaa saman ongelman uudelleen.
5. Jatka porrastetusti. Älä vapauta koko jonoa samanaikaisesti odotuksen päättyessä.

Kun se on tuettu, eräajo voi vähentää pyyntöjen määrää, mutta sen on noudatettava dokumentoituja eräkoko- ja laskentasääntöjä. Älä oleta, että yksi erä kuluttaa yhden yksikön käyttökiintiöstä. Käytä vastaavasti webhookeja, jos ne ovat saatavilla, vähentääksesi tarpeetonta pollausta, mutta säilytä integraation vaatima täsmäytysprosessi.

Käytä rajoitettuja uudelleenyrityksiä, backoff-viivettä ja hajontaa

Uudelleenyritykset ovat asianmukaisia, kun virhe voi poistua ilman pyynnön muuttamista ja toiminnon toistaminen on turvallista. Tilapäiset yhteysvirheet ja tietyt palvelinvirheet voivat kuulua tähän luokkaan. Virheellinen hyötykuorma, virheelliset tunnistetiedot tai pysyvä käyttöoikeusongelma edellyttävät yleensä korjausta.

Käytännöllinen varamenetelmä on rajattu eksponentiaalinen backoff täydellä hajonnalla:

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)

Tässä retry_index alkaa arvosta nolla ensimmäiselle uudelleenyritykselle, eikä puuttuva Retry-After lisää vähimmäisodotusaikaa. Nämä ovat toteutusvalintoja, eivät pakollinen HTTP-algoritmi. Valitse perusviive, yläraja, yritysraja ja kokonaisaikaraja työkuorman ja palveluntarjoajan ohjeiden mukaan.

Hajonta jakaa pyynnöt ajalle sen sijaan, että jokainen työntekijä toistaisi ne samalla aikataululla. Viiveen yläraja rajoittaa eksponentiaalista osuutta; se ei saa ohittaa pidempää, kelvollista palvelimen pyytämää odotusta. Jos odotus ylittää työsi määräajan, siirrä työ myöhemmäksi tai lopeta se käytännön mukaisesti sen sijaan, että yrittäisit liian aikaisin uudelleen.

Aseta jokaiselle uudelleenyritysketjulle päätepiste

• Yritysraja: rajoita lisäpyyntöjen määrää.
• Kuluneen ajan raja: lopeta työn uudelleenyritys, kun sen hyödyllinen käsittelyaika on ylitetty.
• Selkeä omistajuus: valitse, mikä kerros hallitsee uudelleenyrityksiä, jotta HTTP-asiakkaan ja jonon uudelleenyritykset eivät moninkertaistu odottamatta.
• Kestävä ajoitus: tallenna viivästetyt työt sen sijaan, että luottaisit pitkiin odotuksiin lyhytikäisissä prosesseissa.
• Palautuspolku: lähetä loppuun käytetyn budjetin ylittäneet työt tarkistettavissa olevaan epäonnistuneiden töiden jonoon sekä syyn ja seuraavan toimenpiteen kanssa.

Pitkittyneen häiriön aikana kannattaa harkita sulakekatkaisinta, joka keskeyttää rutiinikutsut tilapäisesti ja sallii hallitut palautumistestit. Tämä on sovelluksen vikasietoisuusmalli, ei osoitus siitä, että jokin tietty seurantapalveluntarjoaja vaatisi sitä.

Selvitä epäselvät kirjoitukset ennen niiden lähettämistä uudelleen

Aikakatkaisu kertoo, ettei sovellus vastaanottanut täydellistä vastausta. Se ei todista, että palvelin hylkäsi pyynnön tai ettei se koskaan käsitellyt sitä. Ero on tärkeä seurantanumeroita rekisteröitäessä tai seurantamäärityksiä muutettaessa.

RFC 9110 selittää idempotentit menetelmät ja varoittaa toistamasta automaattisesti ei-idempotentteja pyyntöjä ilman perustetta tietää, että toistaminen on turvallista tai ettei alkuperäistä toimintoa suoritettu. Arvioi dokumentoidut toiminnon semantiikat sen sijaan, että olettaisit jokaisen seurannan päätepisteen toimivan vain lukuun tarkoitetun haun tavoin.

• Käytä palveluntarjoajan dokumentoimaa idempotenssimekanismia, kun sellainen on saatavilla, ja noudata sen laajuus- ja säilytyssääntöjä.
• Säilytä sama idempotenssiavain saman loogisen toiminnon uudelleenyrityksissä; älä oleta, että satunnaista mukautettua otsaketta kunnioitetaan.
• Jos mahdollista, tarkista olemassa oleva rekisteröinti ennen epäselvän kirjoituksen toistamista.
• Käytä paikallista yksilöllisyysrajoitetta, joka vastaa palveluntarjoajan dokumentoitua lähetyksen identiteettiä.
• Tallenna toiminnon tulos, jotta jonon uudelleenluovutus ei automaattisesti käynnistä uutta kirjoitusta.

Erätoiminnoissa tallenna jokaisen kohteen tulos. Yritä uudelleen vain kohteita, jotka on luokiteltu tilapäisesti epäonnistuneiksi, ja täsmäytä kohteet, joiden tulos on edelleen tuntematon. Koko erän toistaminen voi suorittaa onnistuneen työn uudelleen ja kuluttaa käyttökiintiötä tarpeettomasti.

Sovella käytäntöä seurantapalveluntarjoajaasi

17TRACK-integraatiossa käytä Tracking API -sivua ja virallista API-dokumentaatiota palveluntarjoajakohtaisen sopimuksen lähtökohtina. Pidä virheluokittelijasi määritettävissä sen sijaan, että koodaisit yleisen HTTP-oppaan oletukset suoraan ohjelmaan.

Varmista ennen toteutusta kyseisen päätepisteen pyyntöskeema, vastauskuori, kohdetason virheiden merkitykset, nopeusrajoituksen laajuus, erärajoitukset ja päällekkäisten lähetysten säännöt. Jos käytät tapahtumien toimitusta, tarkista myös kuittaus-, todentamis- ja uudelleenlähetysvaatimukset. Tämä opas ei määritä numeerista 17TRACK-nopeusrajoitusta, uudelleenyritysaikataulua tai idempotenssiominaisuutta.

Kirjaa jokainen vahvistettu sääntö kuvaukseen, joka yhdistää palveluntarjoajan vastauksen sovelluksen toimenpiteeseen: korjaa syöte, korjaa määritys, odota, täsmäytä tai eskaloi. Tunnistamattoman virheen on säilytettävä vianmäärityskonteksti ja noudatettava rajattua varapolkua, ei oletusarvoisesti käynnistettävä rajattomia uudelleenyrityksiä.

Seuraa palautumisen laatua ja testaa virhepolut

Kirjaa toiminto, päätepiste, HTTP-tila, sovelluksen virhekoodi, yritysnumero, viive, seuraava ajoitettu toimenpide ja palveluntarjoajan pyyntötunniste, jos se toimitetaan. Vältä API-avainten, tarpeettomien osoitetietojen tai rajoittamattomien vastausrunkosisältöjen tallentamista. Peitä tai hajauta seurannan tunnisteet, kun täydellisiä arvoja ei tarvita.

Seuraa virheellisten syötteiden määrää, rajoituksia, jonon ikää, loppuun käytettyjä uudelleenyrityksiä ja viimeisintä onnistunutta synkronointia erikseen. Integraation HTTP-virheiden määrä voi olla pieni, vaikka se näyttäisi silti vanhentuneita lähetystietoja. Asiakkaille suunnattujen sivujen tulee säilyttää viimeisin tunnettu lähetyksen tila ja erottaa päivityksen epäonnistuminen kuljetusliikkeen ilmoittamasta toimituspoikkeamasta.

Testaa ennen julkaisua virheellinen syöte, kelvolliset tunnisteet ilman tapahtumia, Retry-After-otsakkeen molemmat muodot, puuttuvat otsakkeet, osittaiset erävirheet, kirjoitusten jälkeiset aikakatkaisut ja jonon uudelleenluovutus. Simuloi myös häiriötä, joka kestää tarpeeksi kauan uudelleenyritysbudjetin loppuun kuluttamiseen. Testi läpäistään vain, kun työ pysähtyy tai siirtyy myöhemmäksi ennakoitavasti, onnistuneita kohteita ei toisteta tarpeettomasti ja epäonnistuneet kohteet pysyvät palautettavina.

Usein kysytyt kysymykset

Pitäisikö virheellistä seurantanumeroa yrittää automaattisesti uudelleen?

Ei silloin, kun API hylkää syötteen nimenomaisesti virheellisenä. Korjaa ensin numero, kuljetusliikkeen valinta tai pakolliset kentät. Jos vastaus sen sijaan tarkoittaa, etteivät lähetyksen tapahtumat ole vielä saatavilla, käytä dokumentoitua päivityskulkua sen sijaan, että käsittelisit tilannetta vahvistusvirheenä.

Tarkoittaako HTTP 200, että eräpyyntö onnistui kokonaan?

Ei välttämättä. Tarkista palveluntarjoajan vastausskeemasta toiminto- ja kohdetason tulokset. Tallenna onnistumiset ja eristä virheet, jotta yhden kohteen uudelleenyritys ei toista tarpeettomasti muita.

Kuinka monta uudelleenyritystä seurannan integraation pitäisi sallia?

Yhtä yleispätevää määrää ei ole. Aseta sekä yritysraja että kuluneeseen aikaan perustuva budjetti palveluntarjoajan ohjeiden, toiminnon turvallisuuden ja tuloksen hyödyllisyyden keston perusteella. Ajastettu taustasynkronointi voi sietää erilaista palautumisikkunaa kuin interaktiivinen asiakaspyyntö.

Pitäisikö aikakatkaisu merkitä lähetyksen välittömästi epäonnistuneeksi?

Ei. Pyyntöjen aikakatkaisu on integraation tulos, ei lähetyksen tapahtuma. Säilytä viimeisin tunnettu seurantatila, ajoita turvallinen palautus ja vältä yhteysongelman muuttamista toimituksen epäonnistumisilmoitukseksi.

Mitä pitäisi tapahtua, kun uudelleenyritykset loppuvat?

Siirrä työ kestävään epäonnistuneiden töiden tai tarkistusten jonoon ja säilytä sen vianmäärityskonteksti. Tunnista, edellyttääkö palautuminen syötteen korjaamista, tunnistetietojen palauttamista, palveluntarjoajan apua vai myöhempää hallittua toistoa. Älä hävitä työtä hiljaisesti tai käynnistä samaa rajatonta uudelleenyrityssykliä uudelleen.

Lähteet

• RFC 9110: HTTP Semantics — HTTP-tilojen semantiikka, idempotentit menetelmät, automaattisia uudelleenyrityksiä koskevat näkökohdat ja Retry-After-kenttä.
• RFC 6585: Additional HTTP Status Codes — 429 Too Many Requests -tilan ja valinnaisen Retry-After-otsakkeen määritelmä.
• 17TRACK Tracking API — seuranta-API-tuotteen virallinen aloituspiste.
• 17TRACK API documentation — viite palveluntarjoajakohtaisten integraatiovaatimusten tarkistamiseen.