L'intégration d'une [API SMS au Maroc](/fr/api-sms-maroc/) est souvent très rapide. Mais une fois en production, face à de vrais numéros marocains (IAM, Orange, inwi) et sous la charge d'envois massifs, des erreurs surviennent.
Contrairement aux protocoles SMPP où l'on déchiffre des PDU complexes en hexadécimal, les API REST modernes utilisent les codes de statut HTTP standard. Pourtant, la documentation officielle manque parfois de contexte métier. Qu'est-ce qu'une erreur 400 signifie réellement dans le contexte d'un envoi SMS au Maroc ?
Voici la "cheat sheet" des développeurs marocains : la liste des codes d'erreur API SMS les plus courants, leur signification business réelle, et comment les résoudre sans perdre de temps.
Tableau rapide des erreurs HTTP de l'API SMS
| Code HTTP | Nom de l'erreur | Signification Métier | Résolution rapide |
|---|---|---|---|
| 400 | Bad Request | Le format du numéro est invalide ou le message est vide. | Formatez au standard international (2126...). |
| 401 | Unauthorized | Clé API absente ou expirée. | Vérifiez l'en-tête Authorization: Bearer. |
| 402 | Payment Required | Plus de crédit sur votre compte. | Rechargez votre compte depuis le dashboard. |
| 403 | Forbidden | Sender ID non autorisé ou adresse IP bloquée. | Demandez l'activation du Sender ID au support. |
| 429 | Too Many Requests | Vous envoyez trop vite (Throttling). | Ralentissez la boucle ou passez à l'endpoint Bulk. |
| 500 | Internal Error | La passerelle SMS est en panne (très rare). | Mettez en file d'attente (Queue) et réessayez. |
| 503 | Service Unavailable | Panne réseau côté opérateur (IAM/Inwi/Orange). | Surveillez le DLR, réessayez après 5 minutes. |
Décortiquons les erreurs fatales : 400 et 403
Erreur 400 : Bad Request (L'erreur du développeur)
C'est la cause de 80% des échecs d'intégration initiale.
- La cause locale : Les utilisateurs marocains saisissent souvent leur numéro sous la forme
0661123456. Si vous passez ce numéro tel quel à l'API, elle vous retournera une erreur 400. - La solution : Nettoyez toujours l'entrée. Supprimez les espaces et le
0initial, et préfixez avec212.
Erreur 403 : Forbidden (L'erreur de conformité)
Votre clé API est bonne (vous n'avez pas de 401), mais la requête est rejetée.
- La cause locale : Au Maroc, vous ne pouvez pas utiliser un Sender ID alphanumérique (ex:
MA MARQUE) s'il n'a pas été explicitement approuvé par l'opérateur. Si vous envoyez une requête avecsender: "MON APP"alors qu'il n'est pas whiteliste sur votre compte, vous recevrez un 403. - La solution : Utilisez le Sender ID par défaut fourni lors de vos tests, ou contactez le support pour soumettre le formulaire d'autorisation de votre marque avec votre RC.
Les erreurs de limite : Le fameux 429
Si vous exécutez une simple boucle for en PHP ou Node.js pour envoyer 50 000 SMS promotionnels pour le Black Friday, vous allez frapper un mur très vite.
Erreur 429 : Too Many Requests
Les API REST imposent une limite de débit (Rate Limiting), souvent exprimée en Requêtes par Seconde (RPS).
- Le problème : Envoyer un SMS par requête HTTP dans une boucle asynchrone va saturer la connexion et déclencher des rejets
429. Les messages rejetés seront perdus. - La solution : N'utilisez pas l'endpoint unitaire pour des envois de masse. Utilisez l'endpoint Bulk de l'API (qui accepte un tableau de numéros en un seul payload JSON) pour contourner la limite de débit HTTP.
Ne confondez pas "Succès HTTP" et "Message Reçu"
Un code HTTP 200/202 ne signifie pas que le SMS a été reçu par le client.
Cela signifie uniquement que la passerelle SMS a accepté votre demande. Le message peut encore échouer plus tard si le téléphone est éteint ou si le numéro n'est plus attribué. Pour connaître le vrai statut de livraison (DLR), vous devez impérativement implémenter un Webhook de réception dans votre architecture.
Questions fréquentes
Quelle est la latence d'acheminement sur les réseaux IAM, Inwi et Orange ?
Sur nos routes locales vers Maroc Telecom (IAM), Orange et inwi, la distribution est instantanée et suivie en temps réel par accusé de réception (DLR).
Comment la plateforme gère-t-elle le format des numéros marocains ?
EnvoiSMS normalise automatiquement les numéros saisis (06..., 07..., 00212...) vers le standard E.164 (+212) pour éviter tout échec de distribution.