SMS OTP qui n'arrive pas au Maroc : 7 causes réelles et comment les corriger

C'est un scénario classique quand on intègre de l'authentification OTP au Maroc. Un SMS qui n'arrive pas (ou qui arrive 15 minutes plus tard) n'est pas forcément lié à une panne globale. Souvent, la friction vient d'un détail de configuration de votre côté, ou d'une règle stricte côté opérateur.

Voici les 7 causes les plus fréquentes qui bloquent la réception d'un OTP au Maroc, et comment réagir sans perdre de temps.

### 1. Le Sender ID n'est pas whiteliste chez l'opérateur concerné Un Sender ID peut être validé chez Maroc Telecom, mais pas encore actif chez Orange ou inwi. C'est le motif n°1 des disparités de réception. Si l'API renvoie un HTTP 400 ou 403 avec un message mentionnant une restriction de Sender ID, c'est là qu'il faut creuser. L'activation multi-opérateur n'est jamais instantanée.

### 2. Le numéro de destination est invalide ou mal formaté Au Maroc, le format local (06XXXXXXXX ou 07XXXXXXXX) doit être converti au format international (2126XXXXXXXX) avant l'envoi. Si votre backend ou votre formulaire front-end ne force pas cette conversion, l'opérateur rejettera la requête avec une erreur HTTP 400 Bad Request (Invalid Destination Address).

### 3. La saturation réseau aux heures de pointe Les soirs de Ramadan (juste avant ou après le Ftour) ou les veilles d'Aïd, le trafic SMS explose. Les opérateurs mettent en place des files d'attente (throttling). Un SMS OTP qui prend normalement moins de 3 secondes peut mettre 15 à 20 minutes à arriver. Dans ce cas, votre statut restera bloqué sur Pending.

### 4. Le contenu est détecté comme SPAM Si votre OTP inclut des liens raccourcis (bit.ly), des caractères non standards, ou des mots-clés blacklistés ("gratuit", "gagnez"), le filtre anti-spam réseau peut le bloquer silencieusement. L'API peut renvoyer un statut Delivered alors que le message est bloqué côté opérateur. Restez sur un format ultra-basique : "Votre code de validation est le : 123456."

### 5. Une erreur d'encodage (Unicode vs GSM-7) Si vous envoyez un message OTP en arabe sans configurer l'encodage UCS-2 (ou Unicode) dans les headers de votre requête API, le message peut arriver sous forme de points d'interrogation (????) ou être scindé et rejeté.

### 6. Le mobile du destinataire est hors réseau Cela paraît évident, mais un téléphone en mode avion, éteint, ou sans couverture réseau ne recevra pas le message. L'opérateur gardera le SMS en file d'attente pendant une durée limitée (le Validity Period, souvent 24h à 48h) avant de l'abandonner définitivement (statut Failed).

### 7. Le compte API est à sec ou suspendu Une erreur 401 Unauthorized ou 402 Payment Required dans vos logs indique généralement que votre solde de crédits est épuisé, ou que votre compte a été suspendu pour activité suspecte (volume anormalement élevé).

Ne devinez pas ce qui se passe : écoutez les Webhooks de statut (Delivery Reports ou DLR) que notre API vous renvoie.

• Delivered : Le téléphone a confirmé au réseau qu'il a bien reçu le SMS. Si le client dit qu'il ne l'a pas, demandez-lui de vérifier ses SMS bloqués (filtre anti-spam iOS/Android).
• Pending : Le SMS est dans les serveurs de l'opérateur (IAM, Orange ou inwi). Le téléphone cible est probablement hors ligne ou le réseau est surchargé. Patientez.
• Failed : L'envoi a échoué. Le numéro n'existe pas, n'est plus attribué, ou le SMS a expiré dans la file d'attente.
• Unknown / Rejected : L'opérateur a refusé le message, souvent à cause d'un filtre anti-spam ou d'un Sender ID non autorisé.

Lorsqu'un utilisateur se plaint, effectuez ces 3 vérifications dans vos logs :

1. Vérifiez la réponse de l'API lors de l'envoi initial (POST). Avez-vous reçu un code HTTP 200/202 (Succès) ou une erreur 400/401 ?
2. Consultez le statut DLR final (le webhook). Est-il en Pending, Failed ou Delivered ?
3. Comparez par opérateur. Le problème survient-il uniquement sur les numéros 0661 (IAM) ou 0614 (Orange) ? Cela indique souvent un souci de whitelisting de Sender ID spécifique à un opérateur.

• Corrigez vous-même : Erreurs HTTP 400 (numéro mal formaté, erreur de syntaxe JSON), erreurs 401 (clé API invalide), ou statut Failed isolé sur un seul numéro (souvent lié au mobile du client).
• Contactez le support : Statut Unknown ou Rejected systématique sur vos envois, délais de Pending dépassant les 2 heures sur plusieurs numéros différents, ou un Sender ID qui passe chez Orange mais pas chez inwi. Dans ce cas, ouvrez un ticket avec les message_id concernés pour que nous puissions analyser les logs SMPP bruts côté opérateur.