Rifiuti HTTP negli SMS A2P: come distinguere gli errori di integrazione dai problemi di consegna

Che cosa significa —e che cosa non significa— una risposta HTTP

Una risposta HTTP indica l’esito dello scambio tra il client e l’endpoint secondo l’implementazione dell’API. Da sola, non dimostra che il provider abbia accettato l’SMS per l’elaborazione né che il messaggio sia arrivato sul telefono.

In un’integrazione SMS è utile distinguere tre esiti: la risposta del trasporto HTTP, l’accettazione o il rifiuto della richiesta di invio da parte dell’API e gli stati successivi del messaggio. Per esempio, in SMPP le notifiche di consegna possono essere comunicate tramite messaggi deliver_sm o data_sm: si tratta di meccanismi diversi dalla risposta HTTP iniziale.

Il significato di ogni risposta dipende dal contratto dell’API. Consulta la documentazione ufficiale del provider per sapere che cosa indica il codice HTTP, che cosa conferma il corpo della risposta e come ottenere lo stato successivo del messaggio.

Distingui le fasi prima di diagnosticare

Modella il percorso come una sequenza di fasi osservabili, non come un unico esito di «inviato» o «non riuscito». Questa distinzione evita di attribuire alla rete mobile un problema di autenticazione o di interpretare un’accettazione tecnica come conferma della consegna.

Trasporto HTTP: determina se il client è riuscito a comunicare con l’endpoint e quale risposta ha ricevuto. Un errore di connessione o un timeout non dimostra che l’API non abbia elaborato la richiesta.

Convalida e accettazione: esamina la risposta dell’API in base alla relativa documentazione. Può indicare una richiesta non valida, rifiutata o accettata per una fase successiva; non presumere che tutti i provider utilizzino la stessa struttura o semantica.

Stato successivo: consulta il meccanismo documentato per conoscere l’avanzamento o l’esito dell’SMS, ad esempio una notifica di consegna, quando disponibile. Un DLR comunicato dalla piattaforma non va descritto come una verifica indipendente della ricezione sul dispositivo.

Registra il contesto minimo necessario per ricostruire il caso

I campi da registrare non sono universali: il contratto dell’API e le politiche di sicurezza determinano quali dati sono disponibili e per quanto tempo vengono conservati. Come base operativa, acquisisci gli elementi disponibili che permettono di collegare la richiesta alla risposta e a eventuali stati successivi.

Includi l’ora con il fuso orario, l’identificativo di correlazione del tuo sistema e il riferimento restituito dall’API, se presente. Conserva il metodo e l’endpoint utilizzati, il codice HTTP, la parte pertinente del corpo della risposta e la versione dell’integrazione.

Registra la destinazione nel formato normalizzato che hai inviato e gli attributi tecnici necessari per riprodurre la richiesta, come il tipo di mittente o la codifica, quando fanno parte dell’API. Evita di conservare contenuti o dati personali non necessari alla diagnosi e applica le regole di accesso e conservazione della tua organizzazione.

Non confondere l’identificativo interno della tua applicazione con un riferimento del messaggio assegnato dal provider. Annota chiaramente quale sistema ha generato ciascun identificativo.

• Ora e fuso orario del tentativo.
• Identificativo di correlazione interno e riferimento del provider, se restituito.
• Destinazione normalizzata, metodo ed endpoint; proteggi i dati sensibili.
• Codice HTTP, risposta dell’API ed esito dell’operazione secondo il contratto.
• Stato successivo disponibile e ora in cui è stato osservato.

Classifica il problema in base alla fase e alle evidenze

Non trasformare una tabella generica di codici in una diagnosi definitiva. Le classi di codici HTTP forniscono un contesto sulla risposta del server, ma la causa e l’azione corretta vanno verificate nella documentazione dell’API e confrontate con il corpo della risposta.

Connettività: se non c’è una risposta HTTP, controlla la risoluzione dell’endpoint, la connessione dall’ambiente di invio, i timeout e i registri disponibili su entrambe le estremità. L’assenza di una risposta non dimostra che il server non abbia ricevuto la richiesta.

Autenticazione e autorizzazione: se la risposta o il corpo segnalano problemi di credenziali o permessi, verifica il meccanismo di autenticazione, l’ambiente e i permessi configurati. Non includere segreti nei ticket o nei registri condivisi.

Formato e convalida: se l’API rifiuta dei parametri, confronta la richiesta con lo schema ufficiale: campi obbligatori, formato della destinazione e vincoli documentati. Correggi la richiesta prima di inviarla di nuovo.

Limiti o politiche: se la documentazione o la risposta segnala un limite, una quota o una restrizione, verifica con il provider quale sia il relativo ambito. Non dedurre una frequenza consentita da una singola risposta.

• Individua prima la fase a cui appartiene l’evidenza: trasporto, convalida, accettazione o stato successivo.
• Interpreta insieme il codice HTTP e il corpo della risposta, non uno solo dei due.
• Annota quali conclusioni sono confermate e quali restano ipotesi.

Timeout: esito incerto, non rifiuto confermato

Se il client raggiunge il timeout, potrebbe non sapere se la richiesta è arrivata al server o se il server l’ha elaborata prima che la risposta andasse persa. Se la semantica di idempotenza non è documentata, un nuovo invio può creare un secondo tentativo e, potenzialmente, un messaggio duplicato.

Prima di riprovare, cerca un riferimento o una consultazione dello stato documentati dall’API per quell’operazione. Controlla i registri del mittente e, se possibile, chiedi al provider di verificare se ha ricevuto la richiesta originale. Non inventare una chiave di idempotenza né presumere che ripetere la chiamata sia innocuo.

• Nessuna risposta e nessuna evidenza di ricezione: classifica l’esito come sconosciuto, non come rifiuto dimostrato.
• Rifiuto esplicito, interpretato secondo la documentazione: correggi la causa prima di riprovare.
• Accettazione confermata ma senza uno stato successivo: verifica la consultazione dello stato o il meccanismo delle notifiche prima di inviare di nuovo.

Procedura diagnostica riproducibile

Lavora su un caso autorizzato e controllato, rispettando il consenso e le regole applicabili al traffico. L’obiettivo è isolare la fase che non funziona, non aumentare il volume né provare destinazioni senza autorizzazione.

1. Conserva la richiesta e la risposta osservate, proteggendo credenziali e dati personali. Verifica che il client non scarti il codice HTTP o sostituisca la risposta con un messaggio generico.

2. Consulta il contratto e la documentazione ufficiale della versione dell’API utilizzata. Conferma il significato del codice, i campi della risposta, i riferimenti dei messaggi, il meccanismo di stato e le regole di ripetizione e idempotenza documentate.

3. Confronta la richiesta effettiva con una richiesta valida secondo lo schema pubblicato. Modifica una sola variabile alla volta e riproduci il caso esclusivamente tramite un flusso autorizzato.

4. Correlaziona ora e identificativi con i registri del mittente e del provider. Distingui i fatti osservati dalle deduzioni, per esempio «risposta HTTP ricevuta» rispetto a «messaggio accettato» o «DLR ricevuto».

Decidi se correggere, riprovare o inoltrare il caso al supporto

Correggi l’integrazione quando le evidenze e la documentazione indicano credenziali, permessi, formato o parametri errati. Non segnalare come problema di consegna un caso che non ha ancora superato la convalida dell’API.

Riprova solo quando il contratto dell’API e le evidenze consentono di stabilire che sia sicuro farlo. Se l’operazione potrebbe essere stata elaborata e non esiste una garanzia documentata contro i duplicati, risolvi prima l’incertezza tramite il riferimento, la consultazione dello stato o il supporto del provider.

Inoltra il caso al supporto quando il problema persiste con una richiesta conforme e autorizzata, oppure quando le evidenze collocano l’incidente nel servizio o in una fase successiva sotto la responsabilità del provider. Condividi ora, fuso orario, identificativi, endpoint, codice HTTP e risposta pertinente; oscura i segreti e limita i dati del destinatario a quanto necessario.

• Correggere: rifiuto riconducibile a una richiesta o configurazione che puoi verificare.
• Riprovare: solo in presenza di una regola documentata e senza duplicare un esito incerto.
• Inoltrare al supporto: fornire evidenze correlabili che collochino il problema al di fuori dell’integrazione del mittente.

Che cosa non dedurre da un 2xx, da un errore o dall’assenza di un DLR

Un HTTP 2xx non conferma automaticamente la consegna dell’SMS: può indicare un esito HTTP positivo, il cui significato preciso è definito dall’API. Verifica se il corpo conferma l’accettazione e come vengono comunicati gli stati successivi.

Una risposta HTTP di errore non identifica da sola la causa finale. Può riguardare il trasporto, l’autenticazione, la convalida o un’altra condizione specifica dell’implementazione; consulta la risposta e la documentazione ufficiale.

L’assenza di un DLR non dimostra, da sola, né la consegna né il fallimento. Verifica se la notifica è disponibile, quale significato ha in quel servizio e se ci sono informazioni sufficienti per associarla al messaggio. Distingui sempre lo stato comunicato dalla piattaforma da una conferma indipendente della ricezione sul dispositivo.