Codici di errore SMPP negli SMS A2P: guida operativa per ritentare, correggere e chiudere

Cosa conferma — e cosa non conferma — una risposta a submit_sm

Una risposta submit_sm_resp conferma l'esito di una richiesta nel protocollo SMPP. Il campo command_status della PDU di risposta indica se l'SMSC ha accettato o rifiutato quella richiesta SMPP e, quando applicabile, restituisce un codice di errore.

Un'accettazione tecnica non equivale alla consegna sul terminale. Se command_status indica successo e l'SMSC restituisce un message_id, il messaggio è stato accettato da quel sistema per l'elaborazione successiva. Questo non dimostra, da solo, che il messaggio abbia raggiunto la rete mobile, sia stato consegnato al dispositivo o sia stato visualizzato dall'utente.

La prima regola operativa è separare l'accettazione dalla disponibilità di stati successivi riportati dall'SMSC. Conserva il message_id restituito dall'SMSC insieme all'identificativo interno del messaggio, alla destinazione, alla rotta o connessione utilizzata, al timestamp e ai parametri rilevanti della PDU. Questa correlazione sarà necessaria per interpretare DLR, query_sm, cancel_sm o replace_sm.

• submit_sm_resp con esito positivo: la richiesta SMPP è stata accettata dall'SMSC.
• submit_sm_resp con errore: la richiesta è fallita in questa fase e deve essere classificata prima di inviarla nuovamente.
• DLR o query di stato: riportano stati o informazioni mantenute dall'SMSC e non costituiscono, da soli, una prova indipendente di consegna o ricezione sul terminale.
• message_id: riferimento tecnico per operazioni SMPP successive e per la correlazione degli eventi.

I livelli di stato in SMPP: sessione, accettazione del submit, DLR e stati riportati dall'SMSC

Un'operazione affidabile richiede l'osservazione del ciclo di vita a livelli. Prima c'è la sessione: connettività di trasporto e stato del bind. Poi l'accettazione o il rifiuto di submit_sm. In seguito, se richiesto tramite registered_delivery, l'SMSC può restituire una ricevuta di consegna tramite deliver_sm o data_sm, in base al supporto e alla configurazione dell'SMSC o della connessione. Questi stati restano distinti dall'accettazione iniziale e non costituiscono, da soli, un'evidenza indipendente di consegna o ricezione sul dispositivo.

SMPP opera su una connessione sottostante, solitamente TCP/IP, dalla quale il protocollo si aspetta trasferimento affidabile, controllo di flusso e gestione degli errori di trasporto. Una disconnessione, un timeout o una risposta che non arriva non significano automaticamente che l'SMSC non abbia ricevuto la richiesta. In questo caso esiste il rischio di invio duplicato se si ritenta senza una strategia di correlazione e idempotenza nell'applicazione.

Lo stato interrogabile tramite query_sm può includere ENROUTE, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ACCEPTED, UNKNOWN e REJECTED. Questi stati devono essere conservati esattamente come ricevuti, con l'istante di osservazione e il contesto della rotta. Uno stato successivo può modificare la decisione iniziale presa dopo submit_sm_resp.

• Sessione: connessione attiva e bind valido per il tipo di operazione.
• Accettazione: risultato di command_status in submit_sm_resp.
• Stato successivo: DLR o query_sm, quando disponibili, come informazioni riportate dall'SMSC.
• DLR e query_sm: non devono essere interpretati, da soli, come evidenza indipendente di consegna o ricezione sul terminale.

Perché lo stesso errore non richiede sempre la stessa azione

L'azione non deve dipendere soltanto dal codice. Lo stesso errore può avere conseguenze diverse in base alla destinazione, al volume coinvolto, alla criticità del messaggio, allo stato della sessione, alla ricorrenza e all'eventuale presenza di modifiche recenti alla configurazione. Un ESME_RTHROTTLED isolato richiede una riduzione della pressione; una sequenza persistente sull'intera connessione richiede di rivedere il controllo del ritmo e, possibilmente, di sospendere il flusso.

Definisci una matrice decisionale che combini quattro fattori: classe di errore, portata, criticità ed evidenze disponibili. Classifica la portata come singolo messaggio, destinazione specifica, sessione, connessione o insieme di traffico. Distingui i messaggi che possono scadere funzionalmente, come un OTP, da quelli che tollerano un ritardo. Non amplificare un problema temporaneo con tentativi simultanei e non trasformare un errore di dati in tentativi ripetuti.

La policy deve prevedere limiti espliciti. Ogni tentativo richiede un contatore, un intervallo di attesa, una condizione di uscita e un meccanismo per evitare duplicati quando l'incertezza riguarda la risposta di rete. Quando non esiste una risposta conclusiva, registra il caso come incerto invece di etichettarlo prematuramente come rifiutato o consegnato.

• Ritentare in modo controllato: solo in presenza di segnali temporanei o ambigui che giustifichino un'indagine.
• Correggere e reinviare: quando il codice indica parametri, indirizzamento, credenziali o stato di bind errati.
• Sospendere ed escalare: quando il guasto interessa una sessione, una coda, una capacità o un volume rilevante.
• Chiudere: quando il problema è permanente, il messaggio perde utilità o si esauriscono i limiti definiti dalla policy.

Tassonomia operativa dei codici e degli errori SMPP

La classificazione pratica deve conservare due livelli: la semantica esatta di command_status e una categoria operativa interna. Il primo livello evita la perdita di informazioni. Il secondo facilita automazione, avvisi e decisioni coerenti.

Una tassonomia utile separa gli errori di costruzione della PDU, di sessione e autenticazione, di capacità o limitazione, di indirizzamento, di contenuto o parametri e di sistema o fornitore. Non tutti i codici standard risolvono da soli la causa radice; per esempio, ESME_RSYSERR è definito soltanto come errore di sistema e non specifica durata, origine o possibilità di ritentare.

Non sostituire il valore originale con un'etichetta semplificata. Registra il codice esadecimale, il nome SMPP se esiste, la PDU coinvolta, il sequence_number, il command_status, il message_id quando disponibile, il sistema remoto, i parametri non sensibili di indirizzamento e gli eventi di sessione vicini al guasto.

• Costruzione della PDU: correggere serializzazione, lunghezze, campi e comando.
• Sessione e autenticazione: ripristinare bind e autorizzazioni prima di inviare traffico.
• Capacità: rallentare, applicare un'attesa e monitorare il recupero.
• Indirizzamento: normalizzare i dati e validare la combinazione di indirizzo, TON e NPI.
• Sistema o fornitore: preservare le evidenze, limitare i tentativi e richiedere una definizione documentata se la semantica non è standard.

Errori di sessione e bind: credenziali, autorizzazioni, modalità di bind e stato della connessione

submit_sm può essere emesso solo da una sessione nello stato BOUND_TX o BOUND_TRX. Emetterlo da un altro stato può produrre ESME_RINVBNDSTS, definito come stato di bind non corretto per il comando. L'azione corretta non è reinviare immediatamente lo stesso submit: conferma lo stato della sessione, completa il bind appropriato e verifica che la modalità autorizzata consenta la trasmissione.

Gli errori ESME_RBINDFAIL, ESME_RINVPASWD e ESME_RINVSYSID corrispondono rispettivamente a fallimento del bind, password non valida e identificativo di sistema non valido. Devono essere trattati come errori che richiedono una correzione. Ritentare con le stesse credenziali amplifica i guasti e può rendere più difficile la diagnosi.

Oltre al codice, osserva lo stato della connessione: chiusure di socket, timeout, assenza di risposta, riconnessioni frequenti ed eventi di unbind. Quando una richiesta rimane senza risposta a causa di un incidente di trasporto, non presumere che non sia stata elaborata. Prima di ripeterla, applica controlli di deduplicazione e, se disponibili e appropriati, meccanismi di query o riconciliazione basati sugli identificativi noti.

• Verifica che la sessione sia associata come transmitter o transceiver prima di inviare submit_sm.
• Controlla system_id, password, autorizzazioni e modalità di bind rispetto alla configurazione autorizzata.
• Distingui un rifiuto SMPP esplicito da un timeout o una disconnessione senza risposta.
• Non riprogrammare in parallelo messaggi incerti dopo un guasto di trasporto senza una strategia contro i duplicati.

Errori temporanei: congestione, limiti, capacità e attesa controllata

ESME_RTHROTTLED, codice 0x00000058, indica che l'ESME ha superato i limiti di messaggi consentiti. Deve essere interpretato come un segnale per ridurre il ritmo di invio. Il tentativo immediato, soprattutto da più processi in parallelo, mantiene o aggrava l'eccesso che ha generato il rifiuto.

ESME_RMSGQFUL, codice 0x00000014, indica una coda di messaggi piena. Classificalo come segnale di capacità dell'SMSC o della rotta, distinto dagli errori di formato, credenziali o indirizzamento. Può essere transitorio, ma lo standard non stabilisce una finestra di recupero né garantisce che un tentativo avrà successo.

Applica un'attesa progressiva e un limite di tentativi coerente con l'utilità del messaggio. Riduci la concorrenza o il flusso prima di ritentare. Misura separatamente i rifiuti per limitazione, il tempo necessario al recupero e la portata per connessione o destinazione. Se gli errori persistono, sospendi il traffico coinvolto e apri un'indagine con registri completi.

• ESME_RTHROTTLED: ridurre il ritmo, controllare la concorrenza e ritentare dopo un'attesa.
• ESME_RMSGQFUL: trattare come limitazione di capacità e monitorare l'eventuale recupero.
• Evitare tentativi simultanei e illimitati.
• Interrompere i tentativi quando il messaggio non è più utile, viene raggiunto il massimo definito o l'incidente richiede un'escalation.
• ESME_RSYSERR: investigare prima; lo standard non consente di concludere da solo che sia temporaneo o ritentabile.

Errori permanenti o che richiedono correzione: parametri non validi, indirizzamento, mittente e formato

Gli errori di PDU richiedono una revisione della costruzione del messaggio prima di una nuova presentazione. ESME_RINVMSGLEN indica una lunghezza del messaggio non valida; ESME_RINVCMDLEN, una lunghezza del comando non valida; ed ESME_RINVCMDID, un identificativo di comando non valido. Non sono candidati a un tentativo identico: richiedono la correzione della serializzazione o della logica di integrazione.

In submit_sm, short_message ammette fino a 254 ottetti. La specifica avverte che il limite fisico esatto può variare in base alla rete sottostante. Per messaggi superiori a 254 ottetti è necessario utilizzare message_payload e non deve essere usato short_message contemporaneamente. Questo requisito non sostituisce la validazione delle regole accettate dall'SMSC per codifica, segmentazione e altri parametri.

ESME_RINVSRCADR e ESME_RINVDSTADR indicano rispettivamente indirizzo di origine e destinazione non validi. Esistono inoltre ESME_RINVDSTTON e ESME_RINVDSTNPI per TON e NPI della destinazione. Esamina l'indirizzo come un insieme: valore, TON, NPI e regola di accettazione della connessione. E.164 è un riferimento internazionale per la numerazione, ma un aspetto compatibile con tale riferimento non garantisce che la combinazione di indirizzo, TON, NPI e policy dell'SMSC venga accettata.

Per i mittenti, applica la stessa prudenza: un errore di indirizzo di origine richiede di verificare il valore inviato e i parametri associati, oltre alle regole della connessione. Non tentare di aggirare restrizioni sui mittenti o policy di messaggistica; correggi la configurazione e conferma i requisiti applicabili alla rotta.

• ESME_RINVMSGLEN, ESME_RINVCMDLEN e ESME_RINVCMDID: correggere la PDU; non ripetere senza modifiche.
• ESME_RINVSRCADR e ESME_RINVDSTADR: verificare il valore di origine o destinazione.
• ESME_RINVDSTTON e ESME_RINVDSTNPI: verificare la combinazione di indirizzo, TON e NPI.
• Per messaggi lunghi, non combinare short_message con message_payload.
• Mantenere una validazione prima dell'invio per ridurre i rifiuti evitabili.

Errori ambigui o specifici del fornitore: conservare le evidenze e richiedere una definizione documentata

Non tutti i codici ricevuti hanno una semantica universale. SMPP riserva intervalli per estensioni e fornitori di SMSC. Se ricevi un codice al di fuori della tabella standard, non riassegnarlo a una causa generica né tradurlo come consegna non riuscita senza documentazione. Registra il valore esatto e richiedi al sistema remoto una definizione tecnica documentata.

Anche le ricevute di consegna richiedono cautela. SMPP consente all'SMSC di restituire una delivery receipt tramite deliver_sm o data_sm quando è stata richiesta con registered_delivery, ma il contenuto testuale informativo di una SMSC Delivery Receipt è specifico del fornitore. Non costruire automazioni critiche basandoti soltanto su una stringa testuale ritenuta universale.

Quando presente, network_error_code rappresenta un codice reale di errore di rete specifico della tecnologia. Conserva sia il tipo di rete sia il valore del codice, oltre allo stato SMPP e al testo originale del DLR. Queste evidenze consentono di investigare senza cancellare la distinzione tra una semantica SMPP standard, uno stato riportato dall'SMSC e un codice della rete sottostante.

Un buon fascicolo di escalation include cronologia, PDU e risposte rilevanti, codici originali, identificativi correlati, stato della sessione, percentuale e portata dei guasti, destinazioni coinvolte minimizzate quando necessario e modifiche recenti della configurazione. Evita di includere credenziali o dati non necessari.

• Conservare command_status in esadecimale e la sua interpretazione standard quando disponibile.
• Registrare i testi DLR senza presumere che il loro formato sia portabile tra sistemi.
• Preservare network_error_code con il tipo di rete e il valore originale.
• Richiedere documentazione per codici di estensione o del fornitore.
• Effettuare l'escalation con evidenze tecniche sufficienti e senza esporre segreti di connessione.