Fejlhåndtering i Tracking API: Sådan håndterer du ugyldige trackingnumre, hastighedsbegrænsninger og genforsøg

Håndter API-fejl ved sporing ved at adskille ugyldigt input, midlertidige fejl, hastighedsbegrænsninger og resultater for forsendelsesstatus. Afvis eller korrigér ugyldige sporingsnumre i stedet for at forsøge dem igen uændret, koordinér anmodningsmængden ved begrænsning, og gentag midlertidige fejl med begrænset eksponentiel backoff og jitter. Før du gentager en registrering eller en anden skriveanmodning, skal du fastslå, om det første forsøg lykkedes.

For udviklere, der forbinder sporingsdata med et ordrebehandlingssystem, en lagerplatform eller en kundevendt sporingsside, er målet ikke blot færre mislykkede anmodninger. Det er pålidelig synlighed af forsendelser uden duplikerede registreringer, retry-storme, misvisende leveringsmeddelelser eller unødvendige supportsager.

Klassificér fejlen, før du vælger et svar

En sporingsintegration har flere separate resultater, der skal evalueres: om netværksanmodningen blev gennemført, om API'et accepterede handlingen, om hvert anmodet sporingsobjekt lykkedes, og om forsendelseshændelser er tilgængelige. Hvis alle fire behandles som ét samlet succes- eller fejlsignal, opstår der fejl, som kunne være undgået.

Et vellykket HTTP-svar betyder ikke nødvendigvis, at alle elementer i en batch lykkedes. Omvendt er et vellykket opslag uden sporingshændelser ikke nødvendigvis en API-fejl. Undersøg svarteksten, og anvend udbyderens dokumenterede betydning for hvert resultat.

Betingelse	Anbefalet handling	Gentag uændret?
Misdannet nummer eller ugyldigt felt i anmodningen	Validér og korrigér inputtet	Nej
Manglende eller ugyldige legitimationsoplysninger	Kontrollér legitimationsoplysninger, tilladelser og miljø	Ikke før det er korrigeret
Svar om hastighedsbegrænsning	Forsink det berørte arbejde, og reducér det fælles anmodningspres	Efter den krævede ventetid, hvis det er sikkert
Midlertidig tjenestefejl	Anvend begrænset backoff, og kontrollér om handlingen er sikker	Normalt, inden for et retry-budget
Timeout efter indsendelse af en registrering	Afstem, om registreringen findes	Ikke blindt
Accepteret opslag uden forsendelseshændelser	Følg den dokumenterede sporingslivscyklus	Brug planlagt opdatering, ikke hurtige gentagelser

HTTP-statuskoder er et udgangspunkt, ikke et komplet udbyderspecifikt beslutningstræ. RFC 9110 definerer HTTP-semantik, mens RFC 6585 definerer 429 Too Many Requests. Din integration bør også fortolke dokumenterede applikationsfejlkoder og resultater på elementniveau.

Ugyldige sporingsnumre: adskil forkert input fra manglende hændelser

“Ugyldigt sporingsnummer” kan beskrive forskellige problemer: en misdannet identifikator, en kombination af transportør og nummer, der ikke understøttes, et manglende påkrævet transportørfelt eller en anden udbyderspecifik valideringsfejl. Antag ikke, at et nummer er ugyldigt, blot fordi der ikke returneres sporingshændelser.

Validér uden at beskadige identifikatoren

• Gem sporingsnumre som tekststrenge. Numerisk lagring kan fjerne indledende nuller eller ændre lange identifikatorer.
• Bevar det oprindelige input. Gem en separat normaliseret værdi, så transformationer kan efterprøves.
• Normalisér forsigtigt. Fjern omgivende mellemrum, hvor det er passende, men fjern kun interne tegn eller ændr store og små bogstaver, når dokumenterede regler tillader det.
• Kontrollér påkrævede felter lokalt. Fang tomme numre, manglende transportøridentifikatorer og ugyldige anmodningsstrukturer, før de sendes.
• Undgå et universelt regex til sporingsnumre. En regel, der er udviklet til én transportør, kan afvise gyldige identifikatorer fra en anden.
• Bekræft, hvad feltet indeholder. Et ordrenummer, en lagerreference og et sporingsnummer fra transportøren kan ikke udskiftes, medmindre endpointet udtrykkeligt understøtter dem.

Hvis API'et udtrykkeligt afviser inputtet, skal det sendes til korrektion i stedet for en automatisk retry-løkke. Angiv en nyttig årsag, f.eks. “transportøridentifikator påkrævet”, i stedet for at reducere alle valideringsproblemer til “sporing mislykkedes”.

Behandl “ingen hændelser” som en separat tilstand

En forsendelse kan have en sporingsidentifikator, før nyttige bevægelseshændelser bliver tilgængelige. Det korrekte svar afhænger af API'ets dokumenterede statusmodel og forsendelseskonteksten. Kontrollér, om identifikatoren kom fra forsendelsessystemet, om transportørvalget er korrekt, og om svaret angiver afventende data snarere end afvist input.

Brug særskilte interne tilstande som input_rejected, awaiting_events og temporarily_unavailable. Dette er foreslåede applikationstilstande, ikke standardiserede API-værdier. De hjælper med at forhindre, at et midlertidigt datagab bliver til en unøjagtig kundemeddelelse.

Håndtér hastighedsbegrænsninger på tværs af integrationen, ikke pr. worker

RFC 6585 definerer HTTP 429 som et svar ved hastighedsbegrænsning og tillader, at det indeholder en Retry-After-header. Standarden fastlægger ikke en universel grænse eller tællemetode for sporings-API'er. Begrænsninger kan være dokumenteret pr. konto, legitimationsoplysning, endpoint eller et andet omfang; brug udbyderens faktiske regler.

RFC 9110 specificerer to former for Retry-After: et ikke-negativt antal sekunder eller en HTTP-dato. Analysér begge. Hvis værdien er en dato, skal du beregne den resterende ventetid omhyggeligt og tage højde for forskelle i klokkeslæt. Hvis den mangler eller ikke kan bruges, skal du anvende din konfigurerede fallback-backoff-politik.

Det er ikke nok, at én worker sover, når andre workers fortsætter med at bruge den samme tilladte mængde. Placér hastighedskontrollen ved den fælles grænse for den relevante legitimationsoplysning eller konto. En central planlægger, en delt token bucket eller tilsvarende distribueret kontrol kan koordinere denne trafik.

1. Identificér det berørte omfang. Fastslå, hvilket endpoint, hvilken legitimationsoplysning eller hvilken konto begrænsningen gælder for.
2. Respektér serverens ventetidsinstruktion. Planlæg ikke et tidligere retry end den gyldige Retry-After-værdi tillader.
3. Forsink berørt arbejde i køen. Undgå at blokere uvedkommende trafik, når begrænsningerne reelt er uafhængige.
4. Reducér samtidighed eller anmodningsfrekvens. At vente én gang uden at ændre anmodningsmønstret kan genskabe det samme problem.
5. Genoptag med mellemrum. Frigiv ikke hele backloggen samtidigt, når ventetiden udløber.

Hvor det understøttes, kan batching reducere antallet af anmodninger, men det skal overholde de dokumenterede regler for batchstørrelse og tælling. Antag ikke, at én batch bruger én enhed af den tilladte mængde. Brug ligeledes webhooks, hvor de er tilgængelige, for at reducere unødvendig polling, samtidig med at du opretholder den afstemningsproces, som din integration kræver.

Brug begrænsede retries med backoff og jitter

Retries er passende, når en fejl kan forsvinde uden at ændre anmodningen, og det er sikkert at gentage handlingen. Midlertidige forbindelsesfejl og udvalgte serverfejl kan høre til i denne kategori. En misdannet payload, ugyldige legitimationsoplysninger eller et permanent tilladelsesproblem kræver normalt en korrektion i stedet.

En praktisk fallback er afgrænset eksponentiel backoff med fuld 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 ved nul for det første retry, og en manglende Retry-After bidrager ikke med yderligere minimumsventetid. Dette er implementeringsvalg, ikke en påkrævet HTTP-algoritme. Vælg basisforsinkelse, maksimum, forsøgsgrænse og samlet deadline ud fra din arbejdsbelastning og udbyderens vejledning.

Jitter spreder anmodninger over tid, i stedet for at alle workers gentager dem efter den samme tidsplan. Forsinkelsesgrænsen begrænser den eksponentielle komponent; den bør ikke tilsidesætte en længere, gyldig ventetid, som serveren har anmodet om. Hvis denne ventetid overskrider din jobdeadline, skal du udskyde eller afslutte jobbet i henhold til politikken i stedet for at gentage det for tidligt.

Giv hver retry-kæde et slutpunkt

• Forsøgsgrænse: begræns antallet af yderligere anmodninger.
• Tidsgrænse: stop med at gentage arbejde, der har overskredet sit nyttige behandlingsvindue.
• Udtrykkeligt ejerskab: vælg hvilket lag der styrer retries, så HTTP-klient-retries og kø-retries ikke uventet multipliceres.
• Vedvarende planlægning: gem forsinkede jobs i stedet for at være afhængig af lange sleeps i kortlivede processer.
• Gendannelsessti: send jobs, hvor retries er opbrugt, til en fejlkø, der kan gennemgås, med en årsag og næste handling.

Under et længerevarende udfald kan du overveje en circuit breaker, der midlertidigt sætter rutineopkald på pause og tillader kontrollerede gendannelsesprober. Dette er et mønster for applikationsrobusthed, ikke et bevis på, at en bestemt sporingsudbyder kræver det.

Afklar tvetydige skrivehandlinger, før du sender dem igen

En timeout fortæller dig, at din applikation ikke modtog et komplet svar. Den beviser ikke, at serveren afviste eller aldrig behandlede anmodningen. Denne forskel er vigtig, når du registrerer sporingsnumre eller ændrer sporingskonfiguration.

RFC 9110 forklarer idempotente metoder og advarer mod automatisk at gentage ikke-idempotente anmodninger uden grundlag for at vide, at gentagelse er sikker, eller at den oprindelige handling ikke blev udført. Evaluér den dokumenterede handlingssemantik i stedet for at antage, at hvert sporingsendpoint fungerer som et skrivebeskyttet opslag.

• Brug en udbyderdokumenteret idempotensmekanisme, når den er tilgængelig, og følg dens regler for omfang og opbevaring.
• Bevar den samme idempotensnøgle ved retries af den samme logiske handling; antag ikke, at en vilkårlig brugerdefineret header accepteres.
• Kontrollér, hvis det understøttes, den eksisterende registrering, før du gentager en tvetydig skrivehandling.
• Brug en lokal unikhedsbegrænsning, der stemmer overens med udbyderens dokumenterede forsendelsesidentitet.
• Gem resultatet af handlingen, så en genlevering fra køen ikke automatisk udløser endnu en skrivehandling.

Ved batchhandlinger skal resultatet for hvert element gemmes. Gentag kun elementer, der er klassificeret som midlertidigt mislykkede, og afstem elementer, hvis resultat fortsat er ukendt. Hvis hele batchen afspilles igen, kan vellykket arbejde blive gentaget, og den tilladte anmodningsmængde kan bruges unødvendigt.

Anvend politikken på din sporingsudbyder

Ved en 17TRACK-integration skal du bruge siden Tracking API og den officielle API-dokumentation som udgangspunkt for den udbyderspecifikke kontrakt. Gør din fejlkategorisering konfigurerbar i stedet for at hardkode antagelser fra en generisk HTTP-vejledning.

Før implementeringen skal du bekræfte det relevante endpoints anmodningsskema, svarstruktur, betydningen af fejl på elementniveau, omfanget af hastighedsbegrænsningen, batchbegrænsninger og reglerne for duplikerede indsendelser. Hvis du bruger hændelseslevering, skal du også kontrollere kravene til bekræftelse, godkendelse og genlevering. Denne vejledning foreskriver ikke en numerisk 17TRACK-hastighedsbegrænsning, retry-plan eller idempotensfunktion.

Registrér hver bekræftet regel i en mapping fra udbydersvar til applikationshandling: korrigér input, reparér konfiguration, vent, afstem eller eskalér. En ukendt fejl skal bevare den diagnostiske kontekst og følge en begrænset fallback-sti, ikke som standard føre til ubegrænsede retries.

Overvåg kvaliteten af gendannelse, og test fejlstier

Log handlingen, endpointet, HTTP-status, applikationsfejlkode, forsøgsnummer, latenstid, næste planlagte handling og udbyderens anmodningsidentifikator, når den leveres. Undgå at registrere API-nøgler, unødvendige adresseoplysninger eller ubegrænsede svartekster. Maskér eller hash sporingsidentifikatorer, når de fulde værdier ikke er nødvendige.

Overvåg ugyldige inputrater, throttling, køalder, retries der er opbrugt, og seneste vellykkede synkronisering separat. En integration kan have en lav HTTP-fejlrate og stadig levere forældede forsendelsesoplysninger. Kundevendte sider bør bevare den senest kendte forsendelsesstatus og skelne mellem en opdateringsfejl og en leveringsundtagelse rapporteret af transportøren.

Før udgivelsen skal du teste misdannet input, gyldige identifikatorer uden hændelser, begge former for Retry-After, manglende headers, delvise batchfejl, timeouts efter skrivehandlinger og genlevering fra køen. Simulér også et udfald, der varer længe nok til at opbruge retry-budgettet. Testen består kun, når arbejdet stopper eller udsættes på en forudsigelig måde, vellykkede elementer ikke afspilles unødvendigt, og mislykkede elementer fortsat kan gendannes.

FAQ

Bør et ugyldigt sporingsnummer automatisk gentages?

Ikke når API'et udtrykkeligt afviser inputtet som ugyldigt. Korrigér først nummeret, transportørvalget eller de påkrævede felter. Hvis svaret i stedet betyder, at forsendelseshændelser endnu ikke er tilgængelige, skal du bruge den dokumenterede opdateringsproces i stedet for at behandle det som en valideringsfejl.

Betyder HTTP 200, at en batchanmodning blev fuldstændigt gennemført?

Ikke nødvendigvis. Kontrollér udbyderens svarskema for resultater på handlings- og elementniveau. Gem vellykkede resultater, og isolér fejl, så gentagelse af ét element ikke unødigt gentager resten.

Hvor mange retry-forsøg bør en sporingsintegration tillade?

Der findes ikke et universelt antal. Fastlæg både en forsøgsgrænse og et tidsbudget baseret på udbyderens vejledning, handlingens sikkerhed og hvor længe resultatet forbliver nyttigt. En planlagt baggrundssynkronisering kan tåle et andet gendannelsesvindue end en interaktiv kundeanmodning.

Bør en timeout straks markere en forsendelse som mislykket?

Nej. En timeout for en anmodning er et integrationsresultat, ikke en forsendelseshændelse. Bevar den senest kendte sporingstilstand, planlæg sikker gendannelse, og undgå at omdanne et forbindelsesproblem til en meddelelse om mislykket levering.

Hvad skal der ske, når retries er opbrugt?

Flyt jobbet til en vedvarende fejlkø eller gennemgangskø med den diagnostiske kontekst. Identificér, om gendannelse kræver korrigeret input, gendannede legitimationsoplysninger, hjælp fra udbyderen eller en senere kontrolleret genafspilning. Kassér det ikke lydløst, og genstart ikke den samme ubegrænsede retry-cyklus.

Kilder

• RFC 9110: HTTP Semantics — HTTP-statussemantik, idempotente metoder, overvejelser om automatisk retry og Retry-After-feltet.
• RFC 6585: Additional HTTP Status Codes — definitionen af 429 Too Many Requests og dens valgfrie Retry-After-header.
• 17TRACK Tracking API — officiel indgang til sporings-API-produktet.
• 17TRACK API documentation — reference til kontrol af udbyderspecifikke integrationskrav.