Tassonomia degli errori A2P SMS: come classificare rifiuti, scadenze e risultati incerti

Perché un unico stato di errore non basta per gestire una rotta

Un unico stato di «errore» semplifica il report, ma elimina le informazioni necessarie per decidere cosa fare in seguito. Non è equivalente che una richiesta SMPP venga rifiutata per un indirizzo di destinazione non valido, che l'SMSC accetti il messaggio ma questo scada durante il periodo di validità, oppure che il sistema non riceva un DLR interpretabile.

La tassonomia degli errori A2P SMS deve consentire di confrontare i risultati tra rotte, fornitori, destinazioni e finestre temporali senza sostituire l'evidenza tecnica originale. Il suo obiettivo non è indovinare la causa finale di ogni messaggio, ma organizzare i fatti osservabili e associare a ciascun caso un'azione proporzionata.

Una classificazione utile risponde a quattro domande: dove si è verificato il risultato, se è finale o può evolvere, quale evidenza lo supporta e quale azione è consentita. Questa disciplina riduce i tentativi inutili, evita attribuzioni errate e migliora la qualità delle escalation tecniche.

• Non usare «errore» come causa radice.
• Tenere separati il risultato della richiesta, lo stato di consegna e la causa confermata.
• Distinguere gli stati finali dagli stati intermedi.
• Conservare sempre il codice e il testo originale ricevuti, anche dopo aver applicato una mappatura interna.

Principio di evidenza: fatti osservabili, inferenze e cause confermate

La prima regola è separare il fatto tecnico dalla sua interpretazione. Una risposta SMPP con command_status di successo attesta che l'operazione di protocollo è stata accettata; non conferma che l'SMS sia arrivato al terminale. Allo stesso modo, un DLR con stato DELIVERED è una conferma ricevuta attraverso la catena di consegna, non una verifica indipendente e universale della lettura o della ricezione fisica da parte di una persona.

I DLR possono includere identificativo, data di invio, data di chiusura, stato e codice di errore. Questi campi consentono di ricostruire un ciclo di vita, purché l'identificativo possa essere associato in modo affidabile al messaggio originale. Tuttavia, il formato specifico delle ricevute trasportate in short_message può variare in base al gateway o all'SMSC, quindi il parser deve essere controllato per fornitore o rotta.

L'assenza di un DLR non dimostra di per sé la mancata consegna. Può dipendere dal mancato ricevimento del callback, dall'impossibilità di interpretare il DLR, da un ritardo di riconciliazione o da una policy di reportistica della catena upstream. Deve essere classificata come incertezza fino a quando non saranno disponibili ulteriori evidenze.

• Fatto osservabile: risposta HTTP, submit_sm_resp, DLR, callback, consultazione dello stato o timeout interno.
• Inferenza: «probabile congestione», «possibile restrizione del mittente» o «possibile filtraggio».
• Causa confermata: solo quando un codice, una risposta documentata o un'indagine del fornitore la identifica.
• Livello di confidenza: registrare se la classificazione è diretta, inferita o in attesa di conferma.

Le cinque famiglie operative di risultato

Una tassonomia minima e comparabile può organizzare gli esiti in cinque famiglie. Ogni famiglia deve conservare lo stato originale, l'origine dell'evidenza e il livello di confidenza. Le famiglie non sostituiscono i codici del fornitore: li raggruppano a fini operativi, analitici e decisionali.

La stessa rotta può produrre risultati appartenenti a diverse famiglie. Per questo, non è opportuno valutare una rotta con un'unica percentuale aggregata senza esaminare la composizione degli errori, l'evoluzione temporale e l'evidenza disponibile.

• Rifiuto prima dell'accettazione: la piattaforma locale interrompe il tentativo prima di raggiungere l'SMSC, oppure l'SMSC rifiuta la richiesta. Mantenere distinte entrambe le situazioni. Esempi tecnici possibili: errore di bind, credenziali non valide, indirizzo del mittente non valido o indirizzo di destinazione non valido.
• Errore temporaneo: l'evidenza del fornitore lo identifica espressamente come temporaneo o ritentabile. Non trasformare un errore generico in temporaneo per comodità operativa.
• Errore finale: esiste un risultato negativo finale per il quale la documentazione o l'evidenza disponibile non indica un nuovo tentativo sicuro. Un rifiuto dell'SMSC può appartenere a questa famiglia quando è probabile che si ripeta con la stessa richiesta.
• Scadenza: il messaggio ha esaurito una finestra di validità prima che la consegna fosse completata. Deve essere separata dall'errore finale perché la durata di validità e il caso d'uso sono rilevanti.
• Risultato incerto: l'SMSC potrebbe aver accettato il messaggio, ma non esiste un DLR ricevuto e interpretabile che consenta di chiuderlo come consegnato, non consegnato o scaduto.

Dati da conservare per ogni messaggio

La classificazione sarà debole se i registri non consentono di ricostruire la sequenza. L'identificativo interno deve coesistere con gli identificativi assegnati dalla piattaforma, dal fornitore o dall'SMSC. Il DLR deve essere collegato al messaggio originale senza dipendere esclusivamente da un testo di ricevuta che può variare tra implementazioni.

La destinazione deve essere archiviata in formato internazionale normalizzato secondo la struttura del piano E.164, separata dagli attributi utilizzati per l'instradamento o la segmentazione. La normalizzazione non rende un numero valido, attivo, autorizzato o consegnabile; migliora solo la coerenza nella gestione dei dati e nell'analisi.

È inoltre importante conservare una classificazione controllata del contenuto e del mittente, senza utilizzare questi campi per inferire una causa in assenza di evidenza. Ad esempio, una differenza di comportamento per tipo di mittente può giustificare un'indagine, ma non conferma di per sé una restrizione del mittente.

• Identificativo interno del tentativo e del messaggio logico.
• Identificativi di piattaforma, fornitore, SMSC e DLR quando disponibili.
• Timestamp: creazione, accettazione, invio, aggiornamento, ricezione del DLR e chiusura interna.
• Destinazione normalizzata, paese associato e operatore solo quando il dato esiste con evidenza sufficiente.
• Mittente, tipo di mittente e configurazione rilevante della richiesta.
• Rotta, fornitore, connessione, versione del parser e versione della mappatura.
• Classe di contenuto o caso d'uso: OTP, transazionale o marketing legittimo.
• Stato e codice originali, testo originale, famiglia normalizzata, livello di confidenza e azione successiva.

Come mappare HTTP, SMPP e DLR senza perdere informazioni

La mappatura deve essere un livello aggiuntivo e reversibile. Salvare prima la risposta originale, quindi applicare una regola versionata che produca una categoria operativa. Non sovrascrivere un codice SMPP, uno stato HTTP o il testo di un DLR con un'etichetta interna come «numero non valido» o «filtrato» se tale causa non è confermata.

In SMPP, command_status indica il successo o il fallimento di una richiesta SMPP. Codici come ESME_RINVSRCADR, ESME_RINVDSTADR, ESME_RSYSERR, ESME_RBINDFAIL e ESME_RINVPASWD hanno semantiche tecniche differenti e devono restare disponibili per la diagnosi. Una risposta positiva a submit_sm non deve essere mappata come «consegnato»: può essere mappata, al massimo, come «accettato dall'operazione di protocollo» o come stato intermedio equivalente.

Anche gli stati di consegna richiedono una gerarchia temporale. ENROUTE è intermedio e può evolvere, ad esempio, in DELIVERED o EXPIRED. Un parser non deve chiudere un messaggio in modo irreversibile quando dispone soltanto di uno stato che può cambiare.

• Acquisire: protocollo, endpoint o comando, codice, testo, payload originale e timestamp di ricezione.
• Applicare una regola con versione, ambito e data di entrata in vigore.
• Definire la precedenza tra gli aggiornamenti: un DLR finale valido deve prevalere su uno stato intermedio precedente.
• Mantenere i DLR non interpretabili in una coda di revisione e classificarli temporaneamente come risultato incerto.
• Versionare i parser per fornitore, connessione o rotta quando il formato della ricevuta lo richiede.
• Evitare di dipendere programmaticamente da testi variabili di errori specifici; usarli come evidenza diagnostica conservata.

Classificazione in base all'azionabilità

L'utilità di una tassonomia si dimostra quando guida azioni sicure. Non tutte le categorie autorizzano un nuovo tentativo e non ogni incidente richiede l'interruzione del traffico. L'azione deve dipendere dalla famiglia, dal codice originale, dal caso d'uso, dalla finestra di validità e dall'evidenza accumulata.

Le decisioni devono essere eseguite mediante regole esplicite. Un nuovo tentativo può essere appropriato quando il fornitore identifica il risultato come temporaneo o ritentabile; non deve essere applicato automaticamente ai rifiuti che probabilmente produrranno lo stesso errore con la stessa richiesta. Se esiste incertezza, riconciliare prima lo stato per evitare duplicati.

• Correggere dati o configurazione: applicarlo a evidenze come destinazione non valida, mittente non valido, errore di bind o credenziali errate. Convalidare prima di inviare di nuovo.
• Ritentare in sicurezza: solo con evidenza di temporaneità o ritentabilità, una policy di deduplicazione e una finestra di validità ancora utile.
• Interrompere o limitare il traffico: in caso di aumenti persistenti di rifiuti tecnici, errori di autenticazione, errori di sistema o cambiamenti di comportamento che interessano una rotta. La misura deve essere riesaminata con i dati, non con un'attribuzione automatica.
• Effettuare escalation al fornitore: quando sono presenti codici persistenti, DLR incoerenti, ricevute non interpretabili, discrepanze negli identificativi o crescita dei risultati incerti.
• Mantenere in osservazione e riconciliare: per stati intermedi, assenza di DLR entro la finestra definita o conflitti tra fonti di stato.

Errori ambigui: quando usare «causa non determinata»

Una categoria «causa non determinata» è necessaria quando l'evidenza non consente di identificare una causa concreta. Non è un fallimento dell'analisi: è un modo per impedire che un'ipotesi diventi un dato operativo. Deve essere utilizzata, ad esempio, quando si riceve uno stato generico di mancata consegna senza un codice che distingua tra possibili cause.

Non attribuire automaticamente una mancata consegna a filtraggio dei contenuti, indisponibilità del terminale, restrizione del mittente, congestione o problema di numerazione. Uno stato negativo può coprire diverse cause. L'attribuzione deve attendere un codice specifico, una risposta documentata del fornitore, un'evidenza coerente per segmento o un'indagine confermata.

Affinché questa categoria sia utile, non deve trasformarsi in un contenitore permanente. Ogni caso deve conservare metadati sufficienti per poter essere riclassificato se arriva un DLR tardivo, viene aggiornato il parser o il fornitore fornisce un chiarimento.

• Usare «causa non determinata» quando manca un'evidenza discriminante.
• Non usare questa categoria per nascondere errori del parser, perdita di callback o mancanza di correlazione: registrare tali problemi separatamente.
• Misurarne la proporzione per rotta, fornitore, destinazione e versione dell'integrazione.
• Aprire una revisione se aumenta in modo persistente o se si concentra sulla stessa rotta o sullo stesso formato DLR.
• Riclassificare solo mediante una regola versionata e conservare lo storico della modifica.

Regole diverse per OTP, transazionale e marketing legittimo

La categoria di errore non cambia in base al caso d'uso, ma l'azione può cambiare. Un OTP ha un'utilità limitata nel tempo e richiede particolare attenzione ai nuovi tentativi: inviare un codice duplicato o in ritardo può confondere il destinatario e non risolvere l'accesso. Il sistema deve rispettare la validità del codice ed evitare nuovi tentativi quando non apportano più valore.

I messaggi transazionali possono tollerare una policy di nuovi tentativi diversa se il loro contenuto resta valido e se l'evento non viene duplicato in modo dannoso. Il marketing legittimo richiede una disciplina ancora maggiore: deve essere inviato solo a destinatari per i quali sussistano la base giuridica e i permessi applicabili, e un risultato incerto non deve essere usato per giustificare invii ripetuti.

Il periodo di validità fa parte della decisione. La scadenza indica che il messaggio è rimasto in attesa fino a esaurire una finestra configurata prima di fallire sulla piattaforma. Per questo, analizzare le scadenze insieme alla validità configurata e non solo come indicatore della qualità della rotta.

• OTP: chiusura rapida, deduplicazione rigorosa e nuovo tentativo solo se ancora entro la validità del codice e se la policy lo consente.
• Transazionale: verificare idempotenza, validità dell'evento e rischio di duplicazione prima di ritentare.
• Marketing legittimo: limitare la frequenza, rispettare consenso ed esclusioni applicabili e non usare l'incertezza come motivo per insistere.
• Per tutti i casi: documentare la policy di nuovi tentativi, il numero massimo di tentativi e la condizione di chiusura.