Rejets HTTP en SMS A2P : distinguer les erreurs d’intégration des échecs de livraison

Ce que signifie — et ne signifie pas — une réponse HTTP

Une réponse HTTP indique le résultat de l’échange entre le client et le point de terminaison, selon l’implémentation de l’API. À elle seule, elle ne prouve pas que le fournisseur a accepté le SMS pour traitement ni que le message est arrivé sur le téléphone.

Dans une intégration SMS, il convient de distinguer trois résultats : la réponse du transport HTTP, l’acceptation ou le rejet de la demande d’envoi par l’API, et les états ultérieurs du message. En SMPP, par exemple, les rapports de livraison peuvent être transmis au moyen de messages deliver_sm ou data_sm ; ce sont des mécanismes distincts de la réponse HTTP initiale.

La signification de chaque réponse dépend du contrat de l’API. Consultez la documentation officielle du fournisseur pour savoir ce qu’indique le code HTTP, ce que confirme le corps de la réponse et comment obtenir l’état ultérieur du message.

Distinguez les étapes avant de diagnostiquer

Modélisez le parcours en étapes observables plutôt qu’en un résultat unique « envoyé » ou « échec ». Cette distinction évite d’attribuer un problème d’authentification au réseau mobile ou de prendre une acceptation technique pour une livraison confirmée.

Transport HTTP : déterminez si votre client a pu communiquer avec le point de terminaison et quelle réponse il a reçue. Un échec de connexion ou un délai d’attente dépassé ne prouve pas que l’API n’a pas traité la demande.

Validation et acceptation : examinez la réponse de l’API conformément à sa documentation. Elle peut signaler une demande invalide, rejetée ou acceptée pour une étape ultérieure ; ne supposez pas que tous les fournisseurs utilisent la même structure ou la même sémantique.

État ultérieur : consultez le mécanisme documenté permettant de connaître la progression ou le résultat du SMS, par exemple un rapport de livraison lorsqu’il est disponible. Un DLR communiqué par la plateforme ne doit pas être présenté comme une vérification indépendante de la réception sur le terminal.

Consignez le contexte minimal nécessaire pour reconstituer le cas

Les champs consignés ne sont pas universels : le contrat de l’API et les règles de sécurité déterminent quelles données existent et combien de temps elles sont conservées. Comme base opérationnelle, capturez les éléments disponibles permettant de relier la demande à la réponse et à tout état ultérieur.

Incluez l’heure avec son fuseau horaire, l’identifiant de corrélation de votre système et la référence renvoyée par l’API, le cas échéant. Conservez la méthode et le point de terminaison utilisés, le code HTTP, le corps de réponse pertinent et la version de l’intégration.

Consignez la destination au format normalisé envoyé ainsi que les attributs techniques nécessaires pour reproduire la demande, comme le type d’expéditeur ou l’encodage lorsqu’ils font partie de l’API. Évitez de stocker du contenu ou des données personnelles qui ne sont pas nécessaires au diagnostic, et appliquez les règles d’accès et de conservation de votre organisation.

Ne confondez pas l’identifiant interne de votre application avec une référence de message du fournisseur. Indiquez clairement quel système a généré chaque identifiant.

• Heure et fuseau horaire de la tentative.
• Identifiant de corrélation interne et référence du fournisseur, si elle a été renvoyée.
• Destination normalisée, méthode et point de terminaison ; protégez les données sensibles.
• Code HTTP, réponse de l’API et résultat de l’opération conformément au contrat.
• État ultérieur disponible et heure à laquelle il a été observé.

Classez l’incident selon l’étape et les éléments disponibles

Ne transformez pas un tableau générique de codes en diagnostic définitif. Les plages de codes HTTP donnent des indications sur la réponse du serveur, mais la cause et l’action appropriée doivent être vérifiées dans la documentation de l’API et confrontées au corps de la réponse.

Connectivité : en l’absence de réponse HTTP, vérifiez la résolution du point de terminaison, la connexion depuis l’environnement émetteur, les délais d’attente et les journaux disponibles aux deux extrémités. L’absence de réponse ne prouve pas que le serveur n’a pas reçu la demande.

Authentification et autorisation : si la réponse ou son corps mentionne des identifiants ou des autorisations, vérifiez le mécanisme d’authentification, l’environnement et les autorisations configurées. N’incluez pas de secrets dans des tickets ou des journaux partagés.

Format et validation : si l’API rejette des paramètres, comparez la demande au schéma officiel : champs requis, format de la destination et restrictions documentées. Corrigez la demande avant de la renvoyer.

Limites ou politiques : si la documentation ou la réponse indique une limite, un quota ou une restriction, vérifiez sa portée auprès du fournisseur. Ne déduisez pas un débit autorisé à partir d’une réponse isolée.

• Commencez par repérer l’étape à laquelle apparaissent les éléments observés : transport, validation, acceptation ou état ultérieur.
• Interprétez le code HTTP et le corps de la réponse ensemble, et non séparément.
• Consignez les conclusions confirmées et les hypothèses qui restent à vérifier.

Délai d’attente dépassé : résultat incertain, pas rejet confirmé

Si le client dépasse le délai d’attente, il peut ne pas savoir si la demande est arrivée au serveur ou si celui-ci l’a traitée avant que la réponse ne soit perdue. En l’absence de sémantique d’idempotence documentée, un nouvel envoi peut créer une seconde tentative et, potentiellement, un message en double.

Avant de réessayer, recherchez une référence ou une consultation d’état documentée par l’API pour cette opération. Vérifiez les journaux de l’émetteur et, si possible, demandez au fournisseur de confirmer s’il a reçu la demande initiale. N’inventez pas de clé d’idempotence et ne supposez pas qu’il est sans risque de répéter l’appel.

• Sans réponse ni preuve de réception : classez le résultat comme inconnu, et non comme un rejet avéré.
• Réponse explicite de rejet, interprétée conformément à la documentation : corrigez la cause avant de réessayer.
• Acceptation confirmée, mais sans état ultérieur : examinez la consultation d’état ou le mécanisme de rapports avant tout nouvel envoi.

Procédure de diagnostic reproductible

Travaillez sur un cas autorisé et contrôlé, dans le respect du consentement et des règles applicables au trafic. L’objectif est d’isoler l’étape défaillante, et non d’augmenter le volume ou de tester des destinations sans autorisation.

1. Conservez la demande et la réponse observées, en protégeant les identifiants et les données personnelles. Vérifiez que le client ne supprime pas le code HTTP ou ne remplace pas la réponse par un message générique.

2. Consultez le contrat et la documentation officielle de la version de l’API utilisée. Confirmez la signification du code, les champs de réponse, les références de message, le mécanisme d’état ainsi que les règles de réessai et d’idempotence documentées.

3. Comparez la demande réelle à une demande valide selon le schéma publié. Ne modifiez qu’une variable à la fois et ne reproduisez le test que dans le cadre d’un processus autorisé.

4. Faites correspondre l’heure et les identifiants avec les journaux de l’émetteur et du fournisseur. Distinguez les faits observés des déductions, par exemple « réponse HTTP reçue » par rapport à « message accepté » ou « DLR reçu ».

Décidez s’il faut corriger, réessayer ou faire remonter le problème

Corrigez l’intégration lorsque les éléments disponibles et la documentation désignent des identifiants, des autorisations, un format ou des paramètres incorrects. Ne présentez pas comme un échec de livraison un problème qui n’a pas encore dépassé l’étape de validation de l’API.

Ne réessayez que si le contrat de l’API et les éléments disponibles permettent de déterminer que l’opération est sûre. Si elle a pu être traitée et qu’aucune garantie documentée contre les doublons n’existe, levez d’abord l’incertitude à l’aide de la référence, de la consultation d’état ou du support du fournisseur.

Faites remonter le problème lorsqu’il persiste malgré une demande conforme et autorisée, ou lorsque les éléments situent l’incident au niveau du service ou d’une étape ultérieure relevant du fournisseur. Communiquez l’heure, le fuseau horaire, les identifiants, le point de terminaison, le code HTTP et la réponse pertinente ; masquez les secrets et limitez les données du destinataire au strict nécessaire.

• Corriger : rejet attribuable à une demande ou à une configuration que vous pouvez vérifier.
• Réessayer : uniquement selon une règle documentée et sans risquer de dupliquer un résultat incertain.
• Faire remonter le problème : fournir des éléments corrélables qui situent l’incident en dehors de l’intégration de l’émetteur.

Ce qu’il ne faut pas déduire d’un 2xx, d’une erreur ou de l’absence de DLR

Un HTTP 2xx ne confirme pas automatiquement la livraison du SMS : il peut indiquer que l’échange HTTP a réussi, selon une portée exacte définie par l’API. Vérifiez si le corps confirme l’acceptation et comment les états ultérieurs sont communiqués.

Une réponse HTTP d’erreur ne permet pas non plus, à elle seule, d’identifier la cause finale. Elle peut être liée au transport, à l’authentification, à la validation ou à une autre condition propre à l’implémentation ; consultez la réponse et la documentation officielle.

L’absence de DLR ne prouve, à elle seule, ni la livraison ni l’échec. Déterminez si le rapport est disponible, quelle est sa signification dans ce service et si les informations suffisent à l’associer au message. Distinguez toujours l’état communiqué par la plateforme d’une confirmation indépendante de réception sur l’appareil.