Gestione degli errori dell'API di tracking: come gestire numeri di tracking non validi, limiti di frequenza e ritentativi

Gestisci gli errori dell’API di tracking separando input non validi, errori temporanei, limiti di frequenza e risultati relativi allo stato della spedizione. Rifiuta o correggi i numeri di tracking non validi invece di ritentarli invariati, coordina il volume delle richieste quando sei soggetto a limitazioni e ritenta gli errori temporanei con un backoff esponenziale limitato e un jitter. Prima di ripetere una registrazione o un’altra richiesta di scrittura, stabilisci se il primo tentativo ha avuto esito positivo.

Per gli sviluppatori che collegano i dati di tracking a un sistema di gestione degli ordini, a una piattaforma di magazzino o a una pagina di tracking rivolta ai clienti, l’obiettivo non è semplicemente ridurre le richieste non riuscite. È ottenere una visibilità affidabile sulle spedizioni senza registrazioni duplicate, raffiche di tentativi, messaggi di consegna fuorvianti o richieste di assistenza non necessarie.

Classifica l’errore prima di scegliere una risposta

Un’integrazione di tracking presenta diversi risultati distinti da valutare: se la richiesta di rete è stata completata, se l’API ha accettato l’operazione, se ogni elemento di tracking richiesto ha avuto esito positivo e se gli eventi della spedizione sono disponibili. Trattare tutti e quattro gli aspetti come un singolo indicatore di successo o fallimento crea errori evitabili.

Una risposta HTTP di successo non significa necessariamente che ogni elemento di un batch abbia avuto esito positivo. Al contrario, una ricerca elaborata correttamente ma priva di eventi di tracking non indica necessariamente un errore dell’API. Esamina il corpo della risposta e applica il significato documentato dal provider per ogni risultato.

Condizione	Azione consigliata	Ritentare invariato?
Numero malformato o campo della richiesta non valido	Convalida e correggi l’input	No
Credenziali mancanti o non valide	Controlla credenziali, autorizzazioni e ambiente	Non prima della correzione
Risposta di limite di frequenza	Ritarda il lavoro interessato e riduci la pressione condivisa delle richieste	Dopo l’attesa richiesta, se sicuro
Errore temporaneo del servizio	Applica un backoff limitato e verifica la sicurezza dell’operazione	Generalmente sì, entro un budget di tentativi
Timeout dopo l’invio di una registrazione	Verifica se la registrazione esiste	Non alla cieca
Ricerca accettata senza eventi della spedizione	Segui il ciclo di vita del tracking documentato	Usa un aggiornamento programmato, non tentativi ravvicinati

I codici di stato HTTP forniscono un punto di partenza, non un albero decisionale completo e specifico del provider. RFC 9110 definisce la semantica HTTP, mentre RFC 6585 definisce 429 Too Many Requests. La tua integrazione dovrebbe inoltre interpretare i codici di errore applicativi documentati e i risultati a livello di singolo elemento.

Numeri di tracking non validi: distingui l’input errato dagli eventi mancanti

“Numero di tracking non valido” può descrivere problemi diversi: un identificatore malformato, una combinazione corriere-numero non supportata, un campo obbligatorio del corriere mancante o un altro errore di convalida specifico del provider. Non presumere che un numero sia non valido soltanto perché non vengono restituiti eventi di tracking.

Convalida senza danneggiare l’identificatore

• Memorizza i numeri di tracking come stringhe. La memorizzazione numerica può rimuovere gli zeri iniziali o alterare gli identificatori lunghi.
• Conserva l’input originale. Mantieni un valore normalizzato separato, in modo che le trasformazioni restino verificabili.
• Normalizza con cautela. Rimuovi gli spazi iniziali e finali quando appropriato, ma rimuovi i caratteri interni o modifica maiuscole e minuscole solo quando le regole documentate lo consentono.
• Controlla localmente i campi obbligatori. Intercetta numeri vuoti, identificatori del corriere mancanti e strutture di richiesta non valide prima di inviarli.
• Evita un’espressione regolare universale per i numeri di tracking. Una regola progettata per un corriere può rifiutare identificatori validi di un altro.
• Verifica il contenuto del campo. Un numero d’ordine, un riferimento di magazzino e un numero di tracking del corriere non sono intercambiabili, a meno che l’endpoint non li supporti esplicitamente.

Se l’API rifiuta esplicitamente l’input, indirizzalo alla correzione invece di avviarlo in un ciclo di tentativi automatici. Includi una motivazione utile, ad esempio “identificatore del corriere obbligatorio”, invece di ridurre ogni problema di convalida a “tracking non riuscito”.

Tratta “nessun evento” come uno stato separato

Una spedizione può avere un identificatore di tracking prima che siano disponibili eventi di movimento utili. La risposta corretta dipende dal modello di stato documentato dell’API e dal contesto della spedizione. Verifica se l’identificatore proviene dal sistema di spedizione, se la selezione del corriere è corretta e se la risposta indica dati in attesa anziché un input rifiutato.

Usa stati interni distinti come input_rejected, awaiting_events e temporarily_unavailable. Si tratta di stati applicativi suggeriti, non di valori API standardizzati. Aiutano a impedire che una lacuna temporanea nei dati diventi un messaggio impreciso per il cliente.

Gestisci i limiti di frequenza nell’intera integrazione, non per singolo worker

RFC 6585 definisce HTTP 429 come una risposta di limitazione della frequenza e consente di includere un’intestazione Retry-After. Lo standard non stabilisce una soglia o un metodo di conteggio universale per le API di tracking. I limiti possono essere documentati per account, credenziale, endpoint o altro ambito; usa le regole effettive del provider.

RFC 9110 specifica due forme per Retry-After: un numero non negativo di secondi o una data HTTP. Analizza entrambe. Se il valore è una data, calcola con attenzione l’attesa residua e considera le differenze tra gli orologi. Se manca o non è utilizzabile, applica la tua politica di backoff alternativa configurata.

Quando altri worker continuano a utilizzare la stessa soglia, non è sufficiente che un worker resti in attesa autonomamente. Colloca il controllo della frequenza al confine condiviso per la credenziale o l’account interessato. Un pianificatore centrale, un token bucket condiviso o un controllo distribuito equivalente può coordinare quel traffico.

1. Identifica l’ambito interessato. Determina a quale endpoint, credenziale o account si applica il limite.
2. Rispetta l’istruzione di attesa del server. Non pianificare un nuovo tentativo precedente al momento consentito da un valore valido di Retry-After.
3. Ritarda il lavoro accodato interessato. Evita di bloccare il traffico non correlato quando i limiti sono realmente indipendenti.
4. Riduci la concorrenza o la frequenza delle richieste. Attendere una volta senza modificare il modello di richieste può ricreare lo stesso problema.
5. Riprendi con intervalli. Quando termina l’attesa, non rilasciare simultaneamente l’intera coda arretrata.

Quando supportato, il batching può ridurre il numero di richieste, ma deve rispettare le regole documentate relative alla dimensione dei batch e al conteggio. Non presumere che un batch consumi una sola unità della soglia. Analogamente, usa i webhook quando disponibili per ridurre il polling evitabile, mantenendo al contempo il processo di riconciliazione richiesto dalla tua integrazione.

Usa tentativi limitati con backoff e jitter

I tentativi sono appropriati quando un errore può risolversi senza modificare la richiesta e ripetere l’operazione è sicuro. Gli errori temporanei di connessione e alcuni errori del server possono rientrare in questa categoria. Un payload malformato, una credenziale non valida o un problema permanente di autorizzazione richiedono generalmente una correzione.

Un’alternativa pratica è il backoff esponenziale con limite e jitter completo:

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)

Qui retry_index parte da zero per il primo tentativo e un Retry-After assente non aggiunge alcun tempo minimo di attesa. Si tratta di scelte implementative, non di un algoritmo HTTP obbligatorio. Seleziona il ritardo di base, il limite, il numero massimo di tentativi e la scadenza totale in base al tuo carico di lavoro e alle indicazioni del provider.

Il jitter distribuisce le richieste nel tempo invece di farle ripetere a tutti i worker secondo lo stesso programma. Il limite del ritardo limita la componente esponenziale; non dovrebbe sovrascrivere un’attesa valida più lunga richiesta dal server. Se tale attesa supera la scadenza del job, rimanda o termina il job secondo la policy invece di ritentare in anticipo.

Imposta un termine per ogni catena di tentativi

• Limite dei tentativi: limita il numero di richieste aggiuntive.
• Limite temporale: interrompi i tentativi per il lavoro che ha superato la propria finestra utile di elaborazione.
• Responsabilità esplicita: scegli quale livello controlla i tentativi, affinché i tentativi del client HTTP e quelli della coda non si moltiplichino in modo imprevisto.
• Pianificazione durevole: memorizza i job ritardati invece di affidarti a lunghe attese all’interno di processi di breve durata.
• Percorso di recupero: invia i job esauriti a una coda di job non riusciti esaminabile, indicando il motivo e l’azione successiva.

Durante un’interruzione prolungata, valuta un circuit breaker che sospenda temporaneamente le chiamate di routine e consenta probe di recupero controllate. Si tratta di un modello di resilienza applicativa, non della prova che un determinato provider di tracking lo richieda.

Risolvi le scritture ambigue prima di reinviarle

Un timeout indica che l’applicazione non ha ricevuto una risposta completa. Non dimostra che il server abbia rifiutato o non abbia mai elaborato la richiesta. Questa distinzione è importante quando registri numeri di tracking o modifichi la configurazione del tracking.

RFC 9110 illustra i metodi idempotenti e sconsiglia di ritentare automaticamente richieste non idempotenti senza una base per sapere che la ripetizione sia sicura o che l’operazione originale non sia stata applicata. Valuta la semantica documentata dell’operazione invece di presumere che ogni endpoint di tracking si comporti come una ricerca di sola lettura.

• Usa un meccanismo di idempotenza documentato dal provider quando disponibile, seguendone l’ambito e le regole di conservazione.
• Mantieni la stessa chiave di idempotenza per i tentativi della stessa operazione logica; non presumere che venga accettata una qualunque intestazione personalizzata.
• Se supportato, verifica la registrazione esistente prima di ripetere una scrittura ambigua.
• Usa un vincolo di unicità locale allineato all’identità della spedizione documentata dal provider.
• Memorizza l’esito dell’operazione affinché la riconsegna da parte della coda non attivi automaticamente un’altra scrittura.

Per le operazioni batch, memorizza il risultato di ogni elemento. Ritenta solo gli elementi classificati come temporaneamente non riusciti e riconcilia quelli il cui esito resta sconosciuto. Riprodurre l’intero batch può ripetere il lavoro già riuscito e consumare inutilmente la soglia delle richieste.

Applica la policy al tuo provider di tracking

Per un’integrazione 17TRACK, usa la pagina Tracking API e la documentazione ufficiale dell’API come punti di partenza per il contratto specifico del provider. Mantieni configurabile il classificatore degli errori invece di codificare rigidamente supposizioni tratte da una guida HTTP generica.

Prima dell’implementazione, conferma lo schema della richiesta dell’endpoint pertinente, l’involucro della risposta, il significato degli errori a livello di singolo elemento, l’ambito dei limiti di frequenza, i vincoli dei batch e le regole per gli invii duplicati. Quando utilizzi la consegna degli eventi, verifica inoltre i requisiti di conferma, autenticazione e riconsegna. Questa guida non prescrive un limite numerico di frequenza 17TRACK, un programma di tentativi o una funzionalità di idempotenza.

Registra ogni regola confermata in una mappatura dalla risposta del provider all’azione applicativa: correggere l’input, riparare la configurazione, attendere, riconciliare o inoltrare. Un errore non riconosciuto dovrebbe conservare il contesto diagnostico e seguire un percorso alternativo limitato, non avviare tentativi illimitati per impostazione predefinita.

Monitora la qualità del recupero e testa i percorsi di errore

Registra l’operazione, l’endpoint, lo stato HTTP, il codice di errore applicativo, il numero del tentativo, la latenza, l’azione successiva pianificata e l’identificatore della richiesta del provider quando fornito. Evita di registrare chiavi API, informazioni sull’indirizzo non necessarie o corpi delle risposte senza limitazioni. Oscura o sottoponi ad hashing gli identificatori di tracking quando non sono necessari i valori completi.

Monitora separatamente i tassi di input non validi, la limitazione della frequenza, l’età della coda, i tentativi esauriti e l’ultima sincronizzazione riuscita. Un’integrazione può avere un basso tasso di errori HTTP e continuare a fornire informazioni obsolete sulle spedizioni. Le pagine rivolte ai clienti dovrebbero conservare l’ultimo stato noto della spedizione e distinguere un errore di aggiornamento da un’eccezione di consegna segnalata dal corriere.

Prima del rilascio, testa input malformati, identificatori validi senza eventi, entrambe le forme di Retry-After, intestazioni mancanti, errori parziali dei batch, timeout dopo le scritture e riconsegna dalla coda. Simula inoltre un’interruzione abbastanza lunga da esaurire il budget dei tentativi. Il test ha esito positivo solo quando il lavoro si interrompe o viene rimandato in modo prevedibile, gli elementi riusciti non vengono riprodotti inutilmente e quelli non riusciti restano recuperabili.

Domande frequenti

Un numero di tracking non valido dovrebbe essere ritentato automaticamente?

Non quando l’API rifiuta esplicitamente l’input come non valido. Correggi prima il numero, la selezione del corriere o i campi obbligatori. Se la risposta indica invece che gli eventi della spedizione non sono ancora disponibili, usa il flusso di aggiornamento documentato invece di trattarla come un errore di convalida.

HTTP 200 significa che una richiesta batch è riuscita completamente?

Non necessariamente. Controlla lo schema della risposta del provider per i risultati a livello di operazione e di singolo elemento. Memorizza i successi e isola gli errori, in modo che il tentativo di un elemento non ripeta inutilmente gli altri.

Quanti tentativi dovrebbe consentire un’integrazione di tracking?

Non esiste un numero universale. Imposta sia un limite di tentativi sia un budget temporale in base alle indicazioni del provider, alla sicurezza dell’operazione e al tempo durante il quale il risultato resta utile. Una sincronizzazione in background programmata può tollerare una finestra di recupero diversa da una richiesta interattiva del cliente.

Un timeout dovrebbe contrassegnare immediatamente una spedizione come non riuscita?

No. Un timeout della richiesta è un risultato dell’integrazione, non un evento della spedizione. Conserva l’ultimo stato di tracking noto, pianifica un recupero sicuro ed evita di trasformare un problema di connettività in una notifica di mancata consegna.

Cosa dovrebbe accadere quando i tentativi sono esauriti?

Sposta il job in una coda durevole di job non riusciti o di revisione, conservandone il contesto diagnostico. Identifica se il recupero richiede input corretto, credenziali ripristinate, assistenza del provider o una successiva riproduzione controllata. Non eliminarlo silenziosamente né riavviare lo stesso ciclo illimitato di tentativi.

Fonti

• RFC 9110: HTTP Semantics — semantica degli stati HTTP, metodi idempotenti, considerazioni sui tentativi automatici e campo Retry-After.
• RFC 6585: Additional HTTP Status Codes — definizione di 429 Too Many Requests e relativa intestazione Retry-After opzionale.
• 17TRACK Tracking API — punto di accesso ufficiale al prodotto Tracking API.
• 17TRACK API documentation — riferimento per verificare i requisiti di integrazione specifici del provider.