Feilhåndtering i Tracking API: Slik håndterer du ugyldige sporingsnumre, hastighetsbegrensninger og nye forsøk

Håndter API-feil for sporing ved å skille mellom ugyldig inndata, midlertidige feil, hastighetsbegrensninger og resultater for forsendelsesstatus. Avvis eller korriger ugyldige sporingsnumre i stedet for å prøve dem på nytt uendret, koordiner forespørselsvolumet når du blir begrenset, og prøv midlertidige feil på nytt med begrenset eksponentiell tilbakekobling og jitter. Før du gjentar en registrering eller en annen skriveforespørsel, må du fastslå om det første forsøket var vellykket.

For utviklere som kobler sporingsdata til et ordrebehandlingssystem, en lagerplattform eller en kundevendt sporingsside, er målet ikke bare færre mislykkede forespørsler. Målet er pålitelig innsyn i forsendelser uten doble registreringer, stormer av nye forsøk, misvisende leveringsmeldinger eller unødvendige henvendelser til kundestøtte.

Klassifiser feilen før du velger en respons

En sporingsintegrasjon har flere separate resultater som må vurderes: om nettverksforespørselen ble fullført, om API-et godtok operasjonen, om hvert forespurte sporingselement lyktes, og om forsendelseshendelser er tilgjengelige. Hvis alle fire behandles som ett enkelt suksess- eller feilflagg, oppstår unngåelige feil.

Et vellykket HTTP-svar betyr ikke nødvendigvis at hvert element i en batch lyktes. Omvendt er et vellykket behandlet oppslag uten sporingshendelser ikke nødvendigvis en API-feil. Undersøk svarteksten og bruk leverandørens dokumenterte betydning for hvert resultat.

HTTP-statuskoder er et utgangspunkt, ikke et komplett leverandørspesifikt beslutningstre. RFC 9110 definerer HTTP-semantikk, mens RFC 6585 definerer 429 Too Many Requests. Integrasjonen din bør også tolke dokumenterte applikasjonsfeilkoder og resultater på elementnivå.

Ugyldige sporingsnumre: skill ugyldige inndata fra manglende hendelser

«Ugyldig sporingsnummer» kan beskrive ulike problemer: en feilformatert identifikator, en kombinasjon av transportør og nummer som ikke støttes, et manglende obligatorisk transportørfelt eller en annen leverandørspesifikk valideringsfeil. Ikke anta at et nummer er ugyldig bare fordi ingen sporingshendelser returneres.

Valider uten å skade identifikatoren

• Lagre sporingsnumre som tekststrenger. Numerisk lagring kan fjerne innledende nuller eller endre lange identifikatorer.
• Bevar de opprinnelige inndataene. Oppbevar en separat normalisert verdi slik at transformasjoner kan kontrolleres i ettertid.
• Normaliser forsiktig. Fjern innledende og avsluttende mellomrom der det er riktig, men fjern interne tegn eller endre store og små bokstaver bare når dokumenterte regler tillater det.
• Kontroller obligatoriske felt lokalt. Fang opp tomme numre, manglende transportøridentifikatorer og ugyldige forespørselsstrukturer før de sendes.
• Unngå et universelt regulært uttrykk for sporingsnumre. En regel som er laget for én transportør, kan avvise gyldige identifikatorer fra en annen.
• Bekreft hva feltet inneholder. Et ordrenummer, en lagerreferanse og et sporingsnummer fra transportøren kan ikke brukes om hverandre med mindre endepunktet uttrykkelig støtter dem.

Hvis API-et uttrykkelig avviser inndataene, skal de sendes til korrigering i stedet for en automatisk løkke med nye forsøk. Ta med en nyttig årsak, for eksempel «transportøridentifikator kreves», i stedet for å redusere alle valideringsproblemer til «sporing mislyktes».

Behandle «ingen hendelser» som en separat tilstand

En forsendelse kan ha en sporingsidentifikator før nyttige bevegelseshendelser blir tilgjengelige. Riktig respons avhenger av API-ets dokumenterte statusmodell og forsendelseskonteksten. Kontroller om identifikatoren kom fra forsendelsessystemet, om transportørvalget er riktig, og om svaret angir ventende data i stedet for avviste inndata.

Bruk separate interne tilstander som input_rejected, awaiting_events og temporarily_unavailable. Dette er foreslåtte applikasjonstilstander, ikke standardiserte API-verdier. De bidrar til å hindre at et midlertidig datagap blir til en unøyaktig kundemelding.

Håndter hastighetsbegrensninger på tvers av integrasjonen, ikke per arbeider

RFC 6585 definerer HTTP 429 som et svar ved hastighetsbegrensning og tillater at det inneholder en Retry-After-header. Standarden fastsetter ikke en universell kvote eller tellemetode for sporings-API-er. Begrensninger kan være dokumentert per konto, legitimasjon, endepunkt eller et annet omfang; bruk leverandørens faktiske regler.

RFC 9110 angir to former for Retry-After: et ikke-negativt antall sekunder eller en HTTP-dato. Tolke begge. Hvis verdien er en dato, må du beregne gjenværende ventetid nøye og ta høyde for forskjeller i klokkeslett. Hvis den mangler eller ikke kan brukes, skal du bruke den konfigurerte reservepolicyen for tilbakekobling.

Det er ikke tilstrekkelig at én arbeider sover mens andre arbeidere fortsetter å bruke den samme kvoten. Plasser hastighetskontrollen ved den delte grensen for den aktuelle legitimasjonen eller kontoen. En sentral planlegger, en delt tokenbøtte eller tilsvarende distribuert kontroll kan koordinere trafikken.

1. Identifiser det berørte omfanget. Finn ut hvilket endepunkt, hvilken legitimasjon eller hvilken konto begrensningen gjelder.
2. Respekter serverens ventebeskjed. Ikke planlegg et nytt forsøk tidligere enn en gyldig Retry-After-verdi tillater.
3. Utsett berørt arbeid i køen. Unngå å blokkere urelatert trafikk når begrensningene faktisk er uavhengige.
4. Reduser samtidighet eller forespørselsfrekvens. Å vente én gang uten å endre forespørselsmønsteret kan gjenskape det samme problemet.
5. Gjenoppta med mellomrom. Ikke slipp hele etterslepet løs samtidig når ventetiden er over.

Der det støttes, kan batching redusere antall forespørsler, men den må følge dokumenterte regler for batchstørrelse og beregning. Ikke anta at én batch bruker én kvoteenhet. Bruk også webhooks der det er tilgjengelig, for å redusere unødvendig polling, samtidig som du beholder avstemmingsprosessen integrasjonen krever.

Bruk begrensede nye forsøk med tilbakekobling og jitter

Nye forsøk er hensiktsmessige når en feil kan forsvinne uten at forespørselen endres, og det er trygt å gjenta operasjonen. Midlertidige tilkoblingsfeil og utvalgte serverfeil kan passe i denne kategorien. En feilformatert nyttelast, ugyldig legitimasjon eller et permanent tillatelsesproblem krever vanligvis korrigering i stedet.

En praktisk reserve er avkortet eksponentiell tilbakekobling med full jitter:

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)

Her starter retry_index på null for det første nye forsøket, og en manglende Retry-After bidrar ikke med noen ekstra minimumsventetid. Dette er implementasjonsvalg, ikke en obligatorisk HTTP-algoritme. Velg grunnforsinkelse, maksimum, forsøksgrense og total tidsfrist ut fra arbeidsmengden din og leverandørens veiledning.

Jitter sprer forespørsler over tid i stedet for at alle arbeidere gjentar dem etter samme tidsplan. Forsinkelsesgrensen begrenser den eksponentielle komponenten; den skal ikke overstyre en lengre, gyldig ventetid som serveren har bedt om. Hvis denne ventetiden overskrider jobbens tidsfrist, skal jobben utsettes eller avsluttes i henhold til policy, i stedet for å prøve på nytt for tidlig.

Gi hver kjede av nye forsøk et endepunkt

• Forsøksgrense: begrens antallet ekstra forespørsler.
• Tidsgrense: slutt å prøve på nytt når arbeidet har overskredet sitt nyttige behandlingsvindu.
• Eksplisitt eierskap: velg hvilket lag som styrer nye forsøk, slik at nye forsøk i HTTP-klienten og køen ikke multipliseres uventet.
• Varig planlegging: lagre utsatte jobber i stedet for å stole på lange pauser i kortlivede prosesser.
• Gjenopprettingsvei: send jobber som har brukt opp forsøkene til en gjennomgåelig kø for mislykkede jobber, med årsak og neste handling.

Under et langvarig avbrudd bør du vurdere en kretsbryter som midlertidig setter rutineforespørsler på pause og tillater kontrollerte gjenopprettingssonder. Dette er et mønster for robusthet i applikasjoner, ikke et bevis på at en bestemt sporingsleverandør krever det.

Avklar tvetydige skriveoperasjoner før du sender dem på nytt

Et tidsavbrudd forteller deg at applikasjonen ikke mottok et komplett svar. Det beviser ikke at serveren avviste forespørselen eller aldri behandlet den. Dette skillet er viktig når du registrerer sporingsnumre eller endrer sporingskonfigurasjon.

RFC 9110 forklarer idempotente metoder og advarer mot automatisk å prøve ikke-idempotente forespørsler på nytt uten grunnlag for å vite at gjentakelse er trygg, eller at den opprinnelige operasjonen ikke ble gjennomført. Vurder den dokumenterte operasjonssemantikken i stedet for å anta at alle sporingsendepunkter fungerer som skrivebeskyttede oppslag.

• Bruk en leverandørdokumentert mekanisme for idempotens når den er tilgjengelig, og følg reglene for omfang og oppbevaring.
• Bruk den samme idempotensnøkkelen ved nye forsøk for den samme logiske operasjonen; ikke anta at en vilkårlig egendefinert header blir tatt hensyn til.
• Hvis det støttes, kontroller den eksisterende registreringen før du gjentar en tvetydig skriveoperasjon.
• Bruk en lokal unikhetsbegrensning som er tilpasset leverandørens dokumenterte forsendelsesidentitet.
• Lagre resultatet av operasjonen slik at ny levering fra køen ikke automatisk utløser en ny skriveoperasjon.

For batchoperasjoner må resultatet for hvert element lagres. Prøv bare elementer som er klassifisert som midlertidig mislykkede, på nytt, og avstem elementer der resultatene fortsatt er ukjente. Hvis hele batchen spilles av på nytt, kan vellykket arbeid gjentas og forespørselskvoten brukes unødvendig.

Bruk policyen på sporingsleverandøren din

For en 17TRACK-integrasjon kan du bruke Tracking API-siden og den offisielle API-dokumentasjonen som utgangspunkt for den leverandørspesifikke kontrakten. Hold feilklassifiseringen konfigurerbar i stedet for å hardkode antakelser fra en generell HTTP-veiledning.

Før implementering må du bekrefte det relevante endepunktets forespørselsskjema, svarstruktur, betydningen av feil på elementnivå, omfanget av hastighetsbegrensningen, batchbegrensninger og regler for dupliserte innsendinger. Når du bruker hendelseslevering, må du også kontrollere krav til bekreftelse, autentisering og ny levering. Denne veiledningen foreskriver ikke en numerisk 17TRACK-hastighetsbegrensning, tidsplan for nye forsøk eller idempotensfunksjon.

Registrer hver bekreftede regel i en kobling fra leverandørsvar til applikasjonshandling: korriger inndata, reparer konfigurasjon, vent, avstem eller eskaler. En ukjent feil skal bevare diagnostisk kontekst og følge en begrenset reservevei, ikke som standard føre til ubegrensede nye forsøk.

Overvåk kvaliteten på gjenopprettingen og test feilforløp

Logg operasjonen, endepunktet, HTTP-statusen, applikasjonsfeilkoden, forsøksnummeret, ventetiden, neste planlagte handling og leverandørens forespørselsidentifikator når den oppgis. Unngå å lagre API-nøkler, unødvendig adresseinformasjon eller ubegrensede svartekster. Masker eller hash sporingsidentifikatorer når fullstendige verdier ikke er nødvendige.

Følg ugyldige inndata, hastighetsbegrensninger, køalder, oppbrukte nye forsøk og siste vellykkede synkronisering separat. En integrasjon kan ha lav HTTP-feilrate og likevel vise utdatert forsendelsesinformasjon. Kundevendte sider bør beholde den sist kjente forsendelsesstatusen og skille mellom en feil ved oppdatering og et leveringsavvik rapportert av transportøren.

Før lansering må du teste feilformatert inndata, gyldige identifikatorer uten hendelser, begge formene av Retry-After, manglende headere, delvise batchfeil, tidsavbrudd etter skriveoperasjoner og ny levering fra køen. Simuler også et avbrudd som varer lenge nok til å bruke opp forsøksbudsjettet. Testen er bare vellykket når arbeidet stopper eller utsettes på en forutsigbar måte, vellykkede elementer ikke spilles av på nytt unødvendig, og mislykkede elementer fortsatt kan gjenopprettes.

Vanlige spørsmål

Bør et ugyldig sporingsnummer prøves på nytt automatisk?

Ikke når API-et uttrykkelig avviser inndataene som ugyldige. Korriger nummeret, transportørvalget eller de obligatoriske feltene først. Hvis svaret i stedet betyr at forsendelseshendelser ennå ikke er tilgjengelige, skal du bruke den dokumenterte arbeidsflyten for oppdatering i stedet for å behandle det som en valideringsfeil.

Betyr HTTP 200 at en batchforespørsel ble fullstendig vellykket?

Ikke nødvendigvis. Kontroller leverandørens svarskjema for resultater på operasjons- og elementnivå. Lagre vellykkede resultater og isoler feil, slik at et nytt forsøk for ett element ikke gjentar resten unødvendig.

Hvor mange nye forsøk bør en sporingsintegrasjon tillate?

Det finnes ikke et universelt antall. Fastsett både en forsøksgrense og et tidsbudsjett basert på leverandørens veiledning, operasjonens sikkerhet og hvor lenge resultatet er nyttig. En planlagt synkronisering i bakgrunnen kan tåle et annet gjenopprettingsvindu enn en interaktiv kundeforespørsel.

Bør et tidsavbrudd umiddelbart markere en forsendelse som mislykket?

Nei. Et tidsavbrudd for en forespørsel er et integrasjonsresultat, ikke en forsendelseshendelse. Behold den sist kjente sporingstilstanden, planlegg trygg gjenoppretting og unngå å gjøre et tilkoblingsproblem om til et varsel om mislykket levering.

Hva bør skje når alle nye forsøk er brukt opp?

Flytt jobben til en varig kø for mislykkede jobber eller gjennomgang, sammen med den diagnostiske konteksten. Identifiser om gjenoppretting krever korrigerte inndata, gjenopprettede legitimasjoner, hjelp fra leverandøren eller en senere kontrollert avspilling. Ikke forkast jobben stille eller start den samme ubegrensede løkken på nytt.

Kilder

• RFC 9110: HTTP Semantics — HTTP-statussemantikk, idempotente metoder, hensyn ved automatiske nye forsøk og Retry-After-feltet.
• RFC 6585: Additional HTTP Status Codes — definisjonen av 429 Too Many Requests og den valgfrie Retry-After-headeren.
• 17TRACK Tracking API — offisielt utgangspunkt for sporings-API-produktet.
• 17TRACK API documentation — referanse for kontroll av leverandørspesifikke integrasjonskrav.