Codes d’erreur SMPP en A2P SMS : guide opérationnel pour les tentatives, corrections et clôtures

Ce qu’une réponse submit_sm confirme — et ne confirme pas

Une réponse submit_sm_resp confirme le résultat d’une requête dans le protocole SMPP. Le champ command_status de la PDU de réponse indique si le SMSC a accepté ou rejeté cette requête SMPP et, le cas échéant, renvoie un code d’erreur.

Une acceptation technique n’équivaut pas à une livraison au terminal. Si command_status indique un succès et que le SMSC renvoie un message_id, le message a été accepté par ce système pour traitement ultérieur. Cela ne prouve pas, à lui seul, que le message a atteint le réseau mobile, qu’il a été livré à l’appareil ou que l’utilisateur l’a vu.

La première règle opérationnelle consiste à séparer l’acceptation de la présentation des éléments de preuve de statut ultérieurs. Conservez le message_id renvoyé par le SMSC avec l’identifiant interne du message, la destination, la route ou la connexion utilisée, l’horodatage et les paramètres pertinents de la PDU. Cette corrélation sera nécessaire pour interpréter les DLR, query_sm, cancel_sm ou replace_sm.

• submit_sm_resp avec succès : la requête SMPP a été acceptée par le SMSC.
• submit_sm_resp avec erreur : la requête a échoué à cette étape et doit être classée avant tout nouvel envoi.
• DLR ou consultation de statut : ils apportent des informations ultérieures, mais ne doivent pas être confondus avec une preuve indépendante de réception au terminal.
• message_id : référence technique pour les opérations SMPP ultérieures et la corrélation des événements.

Les couches de statut dans SMPP : session, acceptation du submit, DLR et preuve de réception

Une opération fiable nécessite d’observer le cycle de vie par couches. Il y a d’abord la session : connectivité de transport et état du bind. Viennent ensuite l’acceptation ou le rejet de submit_sm. Plus tard, si cela est demandé via registered_delivery et pris en charge par la route, un accusé de livraison peut arriver via deliver_sm ou data_sm. Enfin, tout élément de preuve de réception indépendant doit être traité comme un signal distinct de la télémétrie du SMSC.

SMPP fonctionne sur une connexion sous-jacente, généralement TCP/IP, dont le protocole attend un transfert fiable, un contrôle de flux et une gestion des erreurs de transport. Une déconnexion, un timeout ou une réponse absente ne signifient pas automatiquement que le SMSC n’a pas reçu la requête. Dans ce cas, un risque de soumission en double existe si elle est renvoyée sans stratégie de corrélation et d’idempotence au niveau de l’application.

Le statut consultable via query_sm peut inclure ENROUTE, DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ACCEPTED, UNKNOWN et REJECTED. Ces statuts doivent être conservés tels qu’ils ont été reçus, avec le moment de l’observation et le contexte de la route. Un statut ultérieur peut modifier la décision initiale prise après submit_sm_resp.

• Session : connexion active et bind valide pour le type d’opération.
• Acceptation : résultat de command_status dans submit_sm_resp.
• Statut ultérieur : DLR ou query_sm, lorsqu’ils sont disponibles.
• Preuve de réception : elle ne doit pas être déduite uniquement d’une acceptation de submit_sm ni d’un format textuel de DLR.

Pourquoi le même échec ne mérite pas toujours la même action

L’action ne doit pas dépendre uniquement du code. Une même erreur peut avoir des conséquences différentes selon la destination, le volume affecté, la criticité du message, l’état de la session, sa récurrence et l’existence de changements récents de configuration. Un ESME_RTHROTTLED isolé impose de réduire la pression ; une séquence persistante sur toute la connexion exige de revoir le contrôle du débit et éventuellement de suspendre le flux.

Définissez une matrice de décision combinant quatre facteurs : classe d’erreur, portée, criticité et éléments de preuve disponibles. Classez la portée comme message individuel, destination spécifique, session, connexion ou ensemble du trafic. Distinguez les messages pouvant expirer fonctionnellement, tels qu’un OTP, de ceux qui peuvent tolérer un retard. N’amplifiez pas un problème temporaire par des tentatives simultanées, et ne transformez pas une erreur de données en tentatives répétées.

La politique doit comporter des limites explicites. Chaque tentative nécessite un compteur, un délai d’attente, une condition de sortie et un mécanisme pour éviter les doublons lorsque l’incertitude porte sur la réponse réseau. Lorsqu’aucune réponse concluante n’est disponible, enregistrez le cas comme incertain au lieu de l’étiqueter prématurément comme rejeté ou livré.

• Réessayer de manière contrôlée : uniquement face à des signaux temporaires ou ambigus justifiant une investigation.
• Corriger et renvoyer : lorsque le code indique des paramètres, un adressage, des identifiants ou un état de bind incorrects.
• Suspendre et escalader : lorsque l’échec touche une session, une file, une capacité ou un volume significatif.
• Clôturer : lorsque le problème est permanent, que le message perd son utilité ou que les limites définies par la politique sont atteintes.

Taxonomie opérationnelle des codes et erreurs SMPP

La classification pratique doit conserver deux niveaux : la sémantique exacte de command_status et une catégorie opérationnelle interne. Le premier niveau évite de perdre de l’information. Le second facilite l’automatisation, les alertes et des décisions cohérentes.

Une taxonomie utile sépare les erreurs de construction de PDU, de session et d’authentification, de capacité ou de limitation, d’adressage, de contenu ou de paramètres, ainsi que les erreurs système ou fournisseur. Tous les codes standard ne permettent pas à eux seuls de déterminer la cause racine ; par exemple, ESME_RSYSERR est uniquement défini comme une erreur système et ne précise ni la durée, ni l’origine, ni la possibilité de réessayer.

Ne remplacez pas la valeur d’origine par une étiquette simplifiée. Enregistrez le code hexadécimal, le nom SMPP s’il existe, la PDU concernée, le sequence_number, le command_status, le message_id lorsqu’il est disponible, le système distant, les paramètres d’adressage non sensibles et les événements de session proches de l’échec.

• Construction de PDU : corriger la sérialisation, les longueurs, les champs et la commande.
• Session et authentification : restaurer le bind et les autorisations avant d’envoyer du trafic.
• Capacité : ralentir, appliquer une attente et surveiller le rétablissement.
• Adressage : normaliser les données et valider la combinaison adresse, TON et NPI.
• Système ou fournisseur : préserver les éléments de preuve, limiter les tentatives et demander une définition documentée si la sémantique n’est pas standard.

Erreurs de session et de bind : identifiants, autorisations, mode de bind et santé de connexion

submit_sm ne peut être émis que depuis une session à l’état BOUND_TX ou BOUND_TRX. L’émettre depuis un autre état peut produire ESME_RINVBNDSTS, défini comme un état de bind incorrect pour la commande. La bonne action n’est pas de renvoyer immédiatement le même submit : confirmez l’état de la session, effectuez le bind approprié et vérifiez que le mode autorisé permet la transmission.

Les erreurs ESME_RBINDFAIL, ESME_RINVPASWD et ESME_RINVSYSID correspondent respectivement à un échec de bind, un mot de passe invalide et un identifiant système invalide. Elles doivent être traitées comme des erreurs nécessitant une correction. Réessayer avec les mêmes identifiants amplifie les échecs et peut compliquer le diagnostic.

Au-delà du code, observez la santé de la connexion : fermetures de socket, timeouts, absence de réponse, reconnexions fréquentes et événements unbind. Lorsqu’une requête reste sans réponse en raison d’un incident de transport, ne supposez pas qu’elle n’a pas été traitée. Avant de la répéter, appliquez des contrôles de déduplication et, lorsqu’ils sont disponibles et appropriés, des mécanismes de consultation ou de rapprochement basés sur les identifiants connus.

• Vérifiez que la session est liée comme émetteur ou émetteur-récepteur avant d’envoyer submit_sm.
• Contrôlez system_id, mot de passe, autorisations et mode de bind par rapport à la configuration autorisée.
• Distinguez un rejet SMPP explicite d’un timeout ou d’une déconnexion sans réponse.
• Ne replanifiez pas en parallèle des messages incertains après une panne de transport sans stratégie contre les doublons.

Erreurs temporaires : congestion, limites, capacité et attente contrôlée

ESME_RTHROTTLED, code 0x00000058, indique que l’ESME a dépassé les limites de messages autorisées. Il doit être interprété comme un signal de réduction du débit d’envoi. Une tentative immédiate, notamment depuis plusieurs processus en parallèle, maintient ou aggrave le dépassement ayant provoqué le rejet.

ESME_RMSGQFUL, code 0x00000014, indique qu’une file de messages est pleine. Classez-le comme un signal de capacité du SMSC ou de la route, distinct des erreurs de format, d’identifiants ou d’adressage. Il peut être transitoire, mais le standard ne fixe pas de fenêtre de rétablissement et ne garantit pas qu’une nouvelle tentative réussira.

Appliquez une attente progressive et une limite de tentatives cohérente avec l’utilité du message. Réduisez la concurrence ou le débit avant de réessayer. Mesurez séparément les rejets dus aux limitations, le délai jusqu’au rétablissement et la portée par connexion ou destination. Si les erreurs persistent, suspendez le trafic affecté et ouvrez une investigation avec des journaux complets.

• ESME_RTHROTTLED : réduire le débit, contrôler la concurrence et réessayer après une attente.
• ESME_RMSGQFUL : traiter comme une limitation de capacité et surveiller le rétablissement.
• Évitez les tentatives simultanées et sans limite.
• Arrêtez les tentatives lorsque le message n’est plus utile, que le maximum défini est atteint ou que l’incident requiert une escalade.
• ESME_RSYSERR : investiguer d’abord ; le standard ne permet pas de conclure à lui seul qu’il est temporaire ou qu’une nouvelle tentative est appropriée.

Erreurs permanentes ou nécessitant une correction : paramètres invalides, adressage, expéditeur et format

Les erreurs de PDU imposent de revoir la construction du message avant une nouvelle soumission. ESME_RINVMSGLEN indique une longueur de message invalide ; ESME_RINVCMDLEN, une longueur de commande invalide ; et ESME_RINVCMDID, un identifiant de commande invalide. Elles ne se prêtent pas à une tentative identique : elles exigent de corriger la sérialisation ou la logique d’intégration.

Dans submit_sm, short_message peut contenir jusqu’à 254 octets. La spécification avertit que la limite physique exacte peut varier selon le réseau sous-jacent. Pour les messages de plus de 254 octets, message_payload doit être utilisé et short_message ne doit pas être employé simultanément. Cette exigence ne remplace pas la validation des règles acceptées par le SMSC pour l’encodage, la segmentation et les autres paramètres.

ESME_RINVSRCADR et ESME_RINVDSTADR indiquent respectivement une adresse source et une adresse destination invalides. ESME_RINVDSTTON et ESME_RINVDSTNPI existent également pour le TON et le NPI de destination. Examinez l’adresse comme un ensemble : valeur, TON, NPI et règle d’acceptation de la connexion. E.164 est une référence internationale de numérotation, mais une apparence compatible avec cette référence ne garantit pas que la combinaison adresse, TON, NPI et politique du SMSC sera acceptée.

Pour les expéditeurs, appliquez la même prudence : une erreur d’adresse source nécessite de vérifier la valeur envoyée et les paramètres associés, ainsi que les règles de la connexion. N’essayez pas de contourner les restrictions d’expéditeur ou les politiques de messagerie ; corrigez la configuration et confirmez les exigences applicables à la route.

• ESME_RINVMSGLEN, ESME_RINVCMDLEN et ESME_RINVCMDID : corriger la PDU ; ne pas répéter sans modification.
• ESME_RINVSRCADR et ESME_RINVDSTADR : vérifier la valeur source ou destination.
• ESME_RINVDSTTON et ESME_RINVDSTNPI : vérifier la combinaison adresse, TON et NPI.
• Pour les messages longs, ne combinez pas short_message et message_payload.
• Maintenez une validation avant envoi afin de réduire les rejets évitables.

Erreurs ambiguës ou spécifiques au fournisseur : préserver les éléments de preuve et demander une définition documentée

Tous les codes reçus n’ont pas une sémantique universelle. SMPP réserve des plages pour les extensions et les fournisseurs de SMSC. Si vous recevez un code hors de la table standard, ne le réattribuez pas à une cause générique et ne le traduisez pas comme un échec de livraison sans documentation. Enregistrez la valeur exacte et demandez au système distant une définition technique documentée.

Les accusés de livraison exigent également de la prudence. SMPP permet au SMSC de renvoyer un delivery receipt via deliver_sm ou data_sm lorsqu’il a été demandé avec registered_delivery, mais le contenu textuel informatif d’un SMSC Delivery Receipt est spécifique au fournisseur. Ne construisez pas d’automatisations critiques uniquement sur une chaîne textuelle supposée universelle.

Lorsqu’il est présent, network_error_code représente un code réel d’erreur réseau spécifique à la technologie. Conservez à la fois le type de réseau et la valeur du code, ainsi que le statut SMPP et le texte DLR d’origine. Ces éléments permettent d’investiguer sans effacer la distinction entre une sémantique SMPP standard, un statut rapporté par le SMSC et un code de réseau sous-jacent.

Un bon dossier d’escalade comprend la chronologie, les PDU et réponses pertinentes, les codes d’origine, les identifiants corrélés, l’état de session, le pourcentage et la portée des échecs, les destinations affectées sous forme minimisée lorsque nécessaire, ainsi que les changements récents de configuration. Évitez d’inclure des identifiants ou des données inutiles.

• Conservez command_status en hexadécimal et son interprétation standard lorsqu’elle existe.
• Enregistrez les textes DLR sans supposer que leur format est portable entre les systèmes.
• Préservez network_error_code avec son type de réseau et sa valeur d’origine.
• Demandez de la documentation pour les codes d’extension ou spécifiques au fournisseur.
• Escaladez avec suffisamment d’éléments techniques sans exposer les secrets de connexion.