Skip to main content
HomeBlogGidsenTime-out bij realtime-trackingverzoek? Te volgen regels voor opnieuw proberen, fallback en status

Time-out bij realtime-trackingverzoek? Te volgen regels voor opnieuw proberen, fallback en status

17TRACK

Wanneer een realtime trackingverzoek een time-out krijgt, moet je de meest recente status van de zending als onbekend behandelen — niet als vertraagd, verloren of onveranderd. Voer alleen opnieuw een poging uit binnen een begrensd tijdsbudget en toon daarna een duidelijk gelabelde laatst bekende update of vraag de gebruiker om het later opnieuw te proberen. Houd gedurende het hele proces de uitkomst van het verzoek, de actualiteit van de gegevens en de werkelijke status van het pakket van elkaar gescheiden.

Time-out van realtime trackingverzoek, opnieuw proberen, terugval en status

Dit onderscheid is belangrijk voor zowel trackingpagina’s die aan klanten worden getoond als systemen die trackinggegevens gebruiken om meldingen of ondersteuningsworkflows te activeren. Een time-out betekent dat er niet op tijd een antwoord is aangekomen. Het zegt niet of de vervoerder een nieuw evenement heeft, of een upstream-service het verzoek heeft verwerkt, of dat het pakket zich heeft verplaatst.

Identificeer eerst wat een time-out kreeg

Een trackingverzoek kan op verschillende punten mislukken: de browser kan stoppen met wachten op je toepassing, je toepassing kan stoppen met wachten op een tracking-API, of die API kan een time-out krijgen tijdens het contact met een andere service. De gebruiker kan in elk geval dezelfde algemene fout zien, maar de juiste vervolgstap verschilt.

  • Time-out aan de clientzijde: De app is gestopt met wachten. Het verzoek aan de serverzijde kan nog steeds zijn voltooid. Controleer je eigen verzoeklogboeken of resultatenopslag voordat je een nieuw verzoek indient dat dubbel werk kan veroorzaken.
  • Netwerk- of verbindingsfout: Je systeem heeft geen bruikbaar antwoord ontvangen. Je weet mogelijk niet of de externe service het verzoek heeft verwerkt.
  • HTTP 504: Een gateway of proxy heeft niet tijdig een antwoord van een upstream-server ontvangen. Dit beschrijft het pad van het verzoek, niet de zending.
  • HTTP 408: De server heeft binnen de tijd waarin deze bereid was te wachten geen volledig verzoekbericht ontvangen. Dit is geen trackingstatus van de vervoerder.
  • HTTP 200 met een oud evenement: Het verzoek is geslaagd, maar de teruggegeven trackinginformatie kan nog steeds verouderd zijn. Een succesvol HTTP-antwoord garandeert niet dat de gegevens actueel zijn.

Registreer deze uitkomsten als diagnosedetails van het verzoek. Vertaal geen van deze uitkomsten naar zendinglabels zoals “onderweg”, “probleem” of “afgeleverd”. Die labels moeten afkomstig zijn van trackinggebeurtenissen of een gedocumenteerd statusveld, niet van de transportlaag.

Gebruik een begrensde nieuwe poging, geen eindeloze lus

Voor een alleen-lezen trackingopzoeking is een nieuwe poging na een time-out vaak redelijk. Deze moet nog steeds beperkt zijn. Herhaalde verzoeken kunnen de belasting van een slecht functionerende service verhogen, het wachten van de gebruiker verlengen en dubbel werk veroorzaken wanneer meerdere applicatielagen onafhankelijk opnieuw proberen.

  1. Stel een totale deadline in. Bepaal hoe lang de gebruikersgerichte bewerking mag duren, inclusief de eerste poging en eventuele nieuwe poging. Geef niet elke poging opnieuw een volledige deadline die langer is dan de tijd die de aanroeper kan wachten.
  2. Controleer of de bewerking veilig kan worden herhaald. Een opzoeking verschilt normaal gesproken van een verzoek dat een zending registreert, instellingen wijzigt of een resource aanmaakt. Speel een statuswijzigend verzoek niet automatisch opnieuw af, tenzij het contract van de provider of je idempotentiecontroles dit veilig maken.
  3. Probeer een tijdelijke fout spaarzaam opnieuw. Gebruik een klein, expliciet budget voor nieuwe pogingen en een vertraging met jitter in plaats van gelijktijdige onmiddellijke nieuwe pogingen vanaf veel clients te versturen.
  4. Volg toepasselijke serverinstructies. Als een antwoord een geldige Retry-After-header bevat, plan dan geen eerdere nieuwe poging. Respecteer ook elke strengere limiet van de toepassing of provider.
  5. Stop wanneer de deadline of het budget is opgebruikt. Schakel over naar een terugvalantwoord en plan indien nodig afzonderlijk een latere reconciliatie.

Een praktisch ontwerp kan één gebruikersgerichte nieuwe poging toestaan als er voldoende tijd over is, en verdere pogingen verplaatsen naar een achtergrondvernieuwing. Dat is een voorbeeld van een beleid, geen universele API-regel. Kies limieten op basis van je serviceniveau-doelen, waargenomen latentie en de documentatie van de provider. Tel ook nieuwe pogingen van HTTP-bibliotheken, gateways en job workers mee; anders kan een ogenschijnlijk bescheiden toepassingsbeleid veel upstream-aanroepen veroorzaken.

Behandel HTTP 429 als een signaal voor een snelheidslimiet en niet als reden om onmiddellijk opnieuw te proberen. HTTP 503 kan wijzen op een tijdelijke onmogelijkheid om het verzoek te verwerken, en een server kan Retry-After leveren. Een 504 kan tijdelijk zijn, maar garandeert niet dat de volgende poging werkt. Authenticatiefouten vereisen doorgaans controles van inloggegevens of rechten, terwijl onjuist gevormde verzoeken om correctie van de invoer vragen. Een tracking-ID die een resultaat “niet gevonden” oplevert, vereist meer zorg: afhankelijk van het gedocumenteerde gedrag van de provider en de fase van de zending kan het te vroeg zijn om een record te vinden, of kan de identifier onjuist zijn. Trek uit één dergelijk resultaat niet de definitieve conclusie dat het pakket niet bestaat.

Kies een terugvaloptie die behoudt wat je weet

De veiligste terugvaloptie is meestal het laatst geverifieerde trackingresultaat, samen met de eigen tijd van de gebeurtenis en een eerlijke aanduiding van de actualiteit. Houd dat resultaat gescheiden van de mislukte huidige aanvraag. Een pagina kan bijvoorbeeld zeggen: “Laatste beschikbare update: Vertrokken uit sorteercentrum. Laatst gecontroleerd: [tijd]. Een nieuwere update is tijdelijk niet beschikbaar.” Neem “Laatst gecontroleerd” alleen op als je systeem dit daadwerkelijk registreert; het is geen vervanging voor de tijd van de gebeurtenis bij de vervoerder.

Gebruik de meest specifieke tijd die je kunt onderbouwen. De tijd van een gebeurtenis bij de vervoerder beschrijft wanneer een gebeurtenis naar verluidt plaatsvond. Het tijdstip waarop je systeem die gebeurtenis ontving, beschrijft de ingestie. Het tijdstip waarop een gebruiker de pagina opende, beschrijft geen van beide. Als de bron geen betrouwbare gebeurtenistijd of tijdzone levert, verzin er dan geen. Als het gecachte resultaat evenmin een geregistreerde ophaaltijd heeft, noem het dan een “laatst beschikbare update” in plaats van te beweren dat het onlangs is vernieuwd.

Een terugvaloptie moet drie grenzen volgen:

  • Toon gecachte gegevens als gecachte gegevens. Presenteer een oudere gebeurtenis niet als het resultaat van het verzoek dat een time-out kreeg.
  • Leid geen voortgang af uit verstreken tijd. Een pakket is niet automatisch “onderweg voor bezorging” alleen omdat het meerdere dagen onderweg is.
  • Verberg wezenlijke onzekerheid niet. Als er geen eerder resultaat is, zeg dan dat tracking tijdelijk niet beschikbaar is in plaats van een verzonnen standaardstatus weer te geven.

Andere terugvalroutes kunnen een eerder gesynchroniseerde trackingopslag, een geautoriseerde opzoeking bij de vervoerder of een latere achtergrondvernieuwing omvatten. Gebruik deze alleen als ze passen bij de zending, je rechten en de voorwaarden van de gegevensbron. Een tweede bron kan andere gebeurtenisnamen of rapportagevertragingen hebben. Behoud daarom de herkomst en voeg tegenstrijdige records niet samen zonder een regel die bepaalt hoe dit moet gebeuren. Als een klant op het resultaat kan handelen, bied dan een manier om opnieuw te proberen of contact op te nemen met support in plaats van oneindig een laadindicator te tonen.

Houd verzoekstatus, actualiteit van gegevens en zendingstatus gescheiden

Dit zijn drie verschillende velden, ook als een gebruikersinterface ze samen weergeeft. Verzoekstatus geeft aan of de opzoeking is geslaagd, een time-out kreeg of een fout opleverde. Actualiteit van gegevens geeft aan wanneer de teruggegeven of opgeslagen informatie is waargenomen. Zendingstatus geeft aan wat de trackingbron over het pakket rapporteert. Door ze te scheiden voorkom je dat een tijdelijke API-fout een geldige bezorggebeurtenis overschrijft of dat een verouderde gebeurtenis “onderweg” als een actuele bewering wordt behandeld.

Een systeem kan bijvoorbeeld een eerder geverifieerde gebeurtenis “Afgeleverd” bevatten terwijl de huidige vernieuwing een time-out krijgt. De bezorggebeurtenis verdwijnt niet. De juiste gecombineerde toestand is dat de laatst beschikbare zendingstatus “afgeleverd” is en dat de meest recente vernieuwing is mislukt. Omgekeerd bevestigt een time-out, als de laatste gebeurtenis “Onderweg” is, niet dat het pakket op dit moment onderweg blijft; de time-out bevestigt alleen dat er geen nieuwer antwoord is verkregen.

Pas een vastgelegde regel toe wanneer gebeurtenissen niet in de juiste volgorde aankomen. Vergelijk gebeurtenis-ID’s, tijdstempels, bron en — waar beschikbaar — de gedocumenteerde statussemantiek van de provider. Ga er niet van uit dat de volgorde waarin je systeem updates ontving dezelfde is als de volgorde waarin de gebeurtenissen van de zending plaatsvonden. Een later aangekomen oudere gebeurtenis mag evenmin automatisch een nieuwere geverifieerde status vervangen. Correcties en uitzonderingen kunnen echter legitiem zijn. Vermijd daarom een algemene regel die statuswijzigingen na levering als onmogelijk behandelt. Behoud de onderliggende gebeurtenissen en onderzoek tegenstrijdigheden in plaats van de geschiedenis stilzwijgend te herschrijven.

Als een provider HTTP 202 retourneert, interpreteer dit dan volgens het contract van dat endpoint: acceptatie van een verzoek betekent op zichzelf niet dat de trackingopzoeking is voltooid. Op dezelfde manier stelt HTTP 200 vast dat een HTTP-verzoek volgens de semantiek van dat endpoint is geslaagd; het bewijst niet dat elk trackingveld aanwezig of actueel is. Breng provider-specifieke antwoordvelden pas in kaart nadat je de documentatie van de provider hebt gecontroleerd.

Maak de fout zichtbaar voor operators zonder klanten ongerust te maken

Een bruikbaar operationeel record bevat de request-ID, het endpoint of de bewerking, het aantal pogingen, de verstreken tijd, de time-outlaag, de HTTP-status als die is ontvangen en of het antwoord afkomstig was van een live opzoeking of een terugvaloptie. Registreer voor trackinggegevens de bron en relevante tijdstempels van gebeurtenissen of ophalen. Behandel trackingnummers en klantinformatie volgens de toegangs- en bewaarbeleidsregels van je organisatie; diagnostische bruikbaarheid is geen reden om volledige identifiers bloot te stellen in onbeperkte logboeken.

Let op patronen in plaats van te vertrouwen op één time-out. Een stijgend time-outpercentage op één vervoerdersroute, herhaalde 429-antwoorden of een groter verschil tussen de tijd van de gebeurtenis bij de vervoerder en de ophaaltijd kunnen op verschillende problemen wijzen. Het eerste kan onderzoek door de provider vereisen, het tweede kan snelheidsbeheersing vereisen en het derde kan een controle van synchronisatie of gebeurtenisbezorging vereisen. Als een toepassing tracking aanbiedt via een provider zoals de 17TRACK Tracking API, gebruik dan de documentatie van die provider om endpoint-specifieke antwoordvelden, verzoeklimieten en foutafhandeling te controleren voordat je deze algemene regels implementeert.

Wees in het bericht aan de klant precies en terughoudend: “We konden tracking op dit moment niet vernieuwen. Hier is de laatst beschikbare update.” Geef een volgende stap wanneer dat helpt, zoals later opnieuw controleren of contact opnemen met support als de zending buiten het door de verkoper of vervoerder opgegeven verwachte bezorgvenster valt. Beloof geen vernieuwingstijd die je systeem niet kan garanderen.

Checklist voor het vrijgeven van een time-outbestendige trackingflow

  • Bevestig welke laag elke time-out oplegt en welke laag verantwoordelijk is voor nieuwe pogingen.
  • Stel een totale deadline voor het verzoek en een afzonderlijk, begrensd budget voor nieuwe pogingen in.
  • Controleer of automatisch opnieuw uitgevoerde bewerkingen veilig kunnen worden herhaald.
  • Respecteer snelheidslimieten en geldige Retry-After-instructies.
  • Sla de uitkomst van het verzoek afzonderlijk op van de zendingstatus en gebeurtenisgeschiedenis.
  • Label terugvalgegevens en bewaar hun bron en tijdstempels wanneer deze beschikbaar zijn.
  • Test scenario’s zonder cache, met verouderde cache, 429, 503, 504 en late antwoorden.
  • Controleer dat een time-out geen onjuiste bezorgmelding kan activeren of een geverifieerde gebeurtenis kan wissen.

De hoofdregel is eenvoudig: probeer een verzoek alleen opnieuw wanneer dit veilig en nuttig is; val alleen terug op informatie die je kunt identificeren; en doe nooit een bewering over de zendingstatus op basis van een HTTP-time-out.

Veelgestelde vragen

Moet ik een trackingverzoek met een time-out onmiddellijk opnieuw proberen?

Niet automatisch. Controleer of de bewerking veilig kan worden herhaald, of de totale deadline tijd overlaat voor een nieuwe poging en of geen snelheidslimiet voorschrijft dat je moet wachten. Een korte, begrensde nieuwe poging met jitter kan geschikt zijn voor een alleen-lezen opzoeking; herhaalde onmiddellijke pogingen zijn geen goede standaard.

Betekent HTTP 504 dat het trackingsysteem van de vervoerder niet werkt?

Nee. Het betekent dat een gateway of proxy niet tijdig een upstream-antwoord heeft ontvangen. Het probleem kan zich overal op dat verzoekpad bevinden. Dit zegt niets definitiefs over de algemene beschikbaarheid van de vervoerder of de toestand van het pakket.

Kan ik de laatst bekende status tonen na een time-out?

Ja, als je deze labelt als de laatst beschikbare informatie en niet als een geslaagde live-vernieuwing. Toon de tijd van de gebeurtenis en de ophaaltijd wanneer deze bekend zijn, en maak duidelijk dat een nieuwere update niet kon worden bevestigd.

Moet een time-out een zending veranderen van “onderweg” naar “probleem”?

Nee. Een time-out is een verzoekfout, geen gebeurtenis van de zending. Wijzig de zendingstatus alleen wanneer een betrouwbare trackingbron een gebeurtenis of status levert die de wijziging ondersteunt.

Wat als het verzoek met een time-out een trackingrecord aanmaakte of registreerde?

Ga er niet van uit dat het is mislukt. Het externe systeem kan het hebben verwerkt voordat het antwoord verloren ging. Controleer of er al een resultaat bestaat en gebruik een gedocumenteerd idempotentiemechanisme of een door de provider goedgekeurde herstelprocedure voordat je het opnieuw indient.

Bronnen