Catalogue des erreurs SMS v2

Utiliser le catalogue

Ce catalogue décrit les codes applicatifs de SMS v2 et les erreurs HTTP de requête prises en charge par ses vues publiques. Le format JSON commun explique error.code, error.message, les details facultatifs et l’identifiant message_id facultatif à la racine. Les champs, codes et messages restent en anglais.

Dans les tableaux, reprendre à l’identique signifie conserver le même chemin, le même corps et la même Idempotency-Key pour la création d’un message ou d’un lot. Une nouvelle clé crée une nouvelle opération et peut provoquer un second SMS. Une réponse mémorisée rejoue son résultat initial, même si le statut du message a changé depuis, sauf après l’effacement ciblé décrit ci-dessous.

Requête et validation

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

HTTP	Code	Cause	Action ou reprise
400	validation_error	Champ absent, inconnu ou invalide ; numéro, texte, expéditeur, date ou destinataires non conformes.	Lire error.details et corriger les champs. Vérifier les limites ci-dessous ; ne pas répéter le même corps invalide.
400	parse_error	Le corps ne peut pas être lu comme du JSON valide.	Corriger la sérialisation JSON avant de soumettre la requête.
400	invalid_organization_header	L’en-tête X-Organization a été fourni.	Retirer cet en-tête et utiliser une clé de l’organisation souhaitée.
400	invalid_idempotency_key	Idempotency-Key est absent ou ne contient pas de 1 à 128 caractères ASCII visibles.	Fournir une valeur valide et stable pour l’opération métier.
400	invalid_schedule	send_at n’est plus dans le futur lors de l’admission initiale.	Choisir une date future. Ne pas modifier la date d’une programmation déjà acceptée pour la rejouer.
400	invalid_sender_name	Le contrôle du nom d’expéditeur rejette sa valeur.	Utiliser un nom valide de 1 à 11 lettres ASCII, chiffres ou espaces internes. Les erreurs de format du corps peuvent aussi être signalées par validation_error.
400	invalid_cursor	Le curseur de pagination est invalide ou appartient à un autre lot.	Reprendre next_cursor sans modification depuis la page précédente du même lot, ou recommencer sa première page.
404	not_found	Route inconnue ou ressource absente de l’organisation de la clé.	Vérifier le chemin, l’identifiant et l’organisation. Une ressource d’une autre organisation reste inaccessible.
405	method_not_allowed	La méthode HTTP ne correspond pas à la route.	Utiliser la méthode indiquée dans la référence.
406	not_acceptable	L’en-tête Accept demande un type de réponse non pris en charge.	Demander application/json.
415	unsupported_media_type	Le type du corps n’est pas pris en charge.	Envoyer du JSON avec Content-Type: application/json.

Authentification et autorisations

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

HTTP	Code	Cause	Action ou reprise
401	invalid_api_key	En-tête incorrect, clé historique, secret invalide, clé inactive ou révoquée, ou contexte de clé non valide.	Vérifier l’authentification Bearer et la clé organisationnelle. Ne pas répéter une clé révoquée.
403	insufficient_permissions	La clé ne possède pas la capacité requise.	Utiliser une clé avec la capacité de l’opération. Pour vérifier un message, il faut delivery.read.
403	sms_unavailable	L’organisation ou SMS n’est pas actif ou disponible ; l’activation nécessaire à l’envoi peut manquer.	Vérifier l’état dans Cloud et contacter l’assistance si nécessaire. Attendre la résolution avant de reprendre.
403	sender_name_unavailable	L’expéditeur demandé n’est pas actif ou autorisé pour cette organisation ; il peut aussi avoir été bloqué avant l’appel fournisseur.	Vérifier le nom dans Cloud. Avec message_id, consulter le message : l’échec peut être mémorisé et un rejeu ne relancera pas l’envoi. Voir les échecs mémorisés ci-dessous.

Les trois conflits HTTP 409

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

HTTP	Code	Cause	Action ou reprise
409	idempotency_conflict	La même clé d’idempotence a déjà été utilisée sur cette ressource avec un autre contenu.	Retrouver la requête originale et corriger le suivi métier. Ne pas changer automatiquement de clé pour contourner le conflit.
409	idempotency_in_progress	La requête identique est encore en cours de traitement.	Attendre, puis reprendre à l’identique avec des tentatives espacées et limitées. Consulter le statut si l’identifiant est déjà connu.
409	insufficient_credits	Les crédits disponibles sont insuffisants ou leur validité est dépassée.	Vérifier available et valid_until, puis régulariser les crédits avant de reprendre. L’admission d’un lot est atomique : cette erreur ne laisse pas un lot partiellement accepté.

Ces trois codes ne se traitent pas par la même boucle de reprise. Aucun ne justifie la création automatique d’une autre clé d’idempotence.

Données personnelles effacées

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

HTTP	Code	Cause	Action ou reprise
410	personal_data_erased	Rejeu de POST /api/sms/v2/messages/ avec la même clé et le même contenu après un effacement ciblé validé et exécuté sur un message dont le traitement est terminé.	Arrêter les reprises de cette opération et conserver sa clé. Ne pas renvoyer le message avec une nouvelle clé.

{
  "error": {
    "code": "personal_data_erased",
    "message": "Personal data for this completed message has been erased. Do not resubmit it with a new idempotency key."
  }
}

Cette réponse remplace la réponse de création mémorisée sans nouvel envoi ni mouvement de crédits. Elle ne signale pas une panne temporaire. Un corps différent avec la même clé reste un 409 idempotency_conflict ; changer le contenu ne contourne pas la protection. Consultez l’idempotence après effacement.

Service et résultat fournisseur

Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.

HTTP	Code	Cause	Action ou reprise
500	internal_error	Une erreur interne empêche de terminer la requête. L’envoi peut déjà avoir commencé.	Reprendre à l’identique avec un nombre limité de tentatives espacées ; consulter le statut si possible. Contacter l’assistance si l’erreur persiste.
503	service_unavailable	Le service est temporairement indisponible, notamment pendant une maintenance.	Attendre et respecter Retry-After lorsqu’il est fourni. Pour une création sans identifiant connu, reprendre avec le même chemin, le même corps et la même Idempotency-Key. Si l’identifiant du message est déjà connu, consulter son statut au retour du service.
503	dispatch_unavailable	La soumission n’a pas pu aboutir. Avec message_id, cette réponse représente un échec mémorisé avant l’appel fournisseur.	Sans message_id, reprendre à l’identique. Avec message_id, consulter le statut ; rejouer la même clé rendra le même échec sans nouvel envoi.
502	provider_rejected	Le fournisseur a explicitement rejeté la soumission.	Conserver message_id et diagnostiquer le rejet. La réponse est mémorisée ; ne pas lancer automatiquement une nouvelle opération.
502	provider_result_unknown	L’acceptation par le fournisseur ne peut pas être déterminée, notamment après une communication interrompue.	Consulter message_id. Ne jamais renvoyer automatiquement avec une nouvelle clé ; le fournisseur peut déjà avoir accepté le SMS.

Aucun débit fixe de requêtes n’est annoncé par ce catalogue. Si un intermédiaire vous renvoie 429, ralentissez et respectez Retry-After lorsqu’il existe ; cela ne constitue pas un quota SMS v2 publié.

Une réponse service_unavailable ne demande pas de créer une autre clé d’idempotence. Conservez l’intention initiale, espacez et limitez les tentatives ; contactez l’assistance si l’indisponibilité persiste. Cette réponse n’annonce pas de date de rétablissement.

Résultat inconnu et échecs mémorisés

Exemple de réponse après un résultat fournisseur incertain :

{
  "error": {
    "code": "provider_result_unknown",
    "message": "The provider outcome is uncertain. Check the message status; do not submit it with a new idempotency key."
  },
  "message_id": "11111111-1111-4111-8111-111111111111"
}

Utilisez GET /api/sms/v2/messages/{message_id}/ avec une clé possédant delivery.read. Un résultat unknown ne prouve ni un rejet ni une absence de livraison. Les crédits peuvent rester réservés pendant la vérification. Le rejeu de la création conserve la réponse initiale ; la consultation du message fournit son état actuel.

provider_rejected, dispatch_unavailable avec message_id et sender_name_unavailable avec message_id peuvent correspondre à des échecs définitifs de cette soumission. Une correction de l’expéditeur ou du service ne transforme pas leur rejeu en nouvel envoi. Après vérification d’un échec certain et résolution de sa cause, une nouvelle tentative métier volontaire exige une nouvelle clé. Ne prenez jamais cette décision automatiquement pour provider_result_unknown, unknown ou une simple réponse réseau perdue.

Pour une programmation déjà acceptée, suivez les statuts des messages. Un lot peut présenter des résultats individuels différents après son admission, et rejouer sa création ne reprogramme pas les destinataires en échec.

Limites fonctionnelles

Les destinataires doivent être des numéros mobiles malgaches au format E.164, par exemple +261321234567, sans espaces. Le texte est limité à deux segments SMS ; le nombre de caractères possible dépend de son encodage. Une programmation utilise une date future RFC 3339 avec fuseau explicite.

Un lot est uniquement programmé : ses destinataires sont distincts et partagent le texte, l’expéditeur et la date. Sa limite est de 1 000 destinataires, conformément au schéma recipients de la référence. Les pages de consultation contiennent au plus 100 messages. Voir le guide des lots et les crédits.