Comprendre les erreurs

Périmètre du format

Les opérations publiques SMS v2 partagent le format d’erreur décrit ici. Il ne s’applique pas automatiquement à SMS v1, aux interfaces internes de Cloud ou à de futurs produits. Le catalogue SMS v2 détaille chaque code et la conduite à tenir.

Une erreur combine un statut HTTP et un objet JSON error. Les noms de champs, les codes et les messages restent en anglais, quelle que soit la langue du portail ou l’en-tête Accept-Language.

Exemple de réponse à une création de message sans en-tête d’authentification :

{
  "error": {
    "code": "invalid_api_key",
    "message": "Use Authorization: Bearer with an organization API key."
  }
}

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

Champ	Usage
error.code	Identifiant stable à utiliser dans votre logique de traitement.
error.message	Explication lisible pour le diagnostic. Ne dépendez pas de son texte exact.
error.details	Informations complémentaires facultatives, notamment les erreurs de validation par champ.
message_id	Identifiant facultatif à la racine pour consulter le message concerné. Sa présence ne prouve pas une acceptation ou une livraison.

Lire HTTP et le code ensemble

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

Statut	Interprétation pour SMS v2
400	Requête invalide : corps, champ, en-tête, date ou curseur à corriger.
401	Authentification absente ou clé non valide.
403	Capacité, activation ou autorisation de l’expéditeur insuffisante.
404	Route ou ressource introuvable dans l’organisation de la clé.
405	Méthode HTTP non prise en charge sur cette route.
406	Type de réponse demandé incompatible avec JSON.
409	Examiner le code : crédits insuffisants, conflit d’idempotence ou traitement en cours.
415	Type du corps incompatible avec application/json.
500	Erreur interne ; elle ne prouve pas que l’envoi n’a pas eu lieu.
502	Rejet fournisseur connu ou résultat inconnu, selon le code.
503	Service ou soumission indisponible ; la reprise dépend du code et d’une éventuelle réponse mémorisée.

Un 201 d’envoi immédiat signifie que le fournisseur a accepté le SMS. Un 202 de programmation signifie que l’API a accepté la programmation et réservé les crédits. Aucun de ces statuts ne confirme la livraison au destinataire : consultez les statuts SMS.

Reprendre sans dupliquer

Pour la création d’un message ou d’un lot, conservez le chemin, le corps et Idempotency-Key dès la première tentative. Après une coupure réseau ou une erreur transitoire, reprenez avec ces mêmes valeurs et espacez les tentatives. Respectez Retry-After lorsqu’il est fourni ; son absence n’autorise pas une boucle rapide.

Une réponse d’erreur peut être mémorisée par l’idempotence. La rejouer ne relance alors pas l’envoi. En particulier, provider_result_unknown exige de consulter le statut du message et interdit une nouvelle soumission automatique avec une autre clé. Suivez la décision propre à chaque code dans le catalogue SMS, puis le guide Idempotence et reprises.

Les règles de reprise des créations de messages et de lots ne constituent pas un mécanisme d’idempotence commun à toutes les opérations. La gestion des contacts suit son contrat de création ou mise à jour.

Si la réponse n’a pas ce format

Une interruption réseau ou une réponse provenant d’un intermédiaire HTTP peut ne contenir aucun JSON exploitable. Vérifiez le statut et Content-Type avant de lire le corps. Ne déduisez pas une absence d’envoi d’une réponse vide, d’un code inconnu ou d’une page HTML.

Conservez l’heure avec son fuseau, la méthode, le chemin, le statut, le code et les identifiants utiles à votre suivi. Masquez les secrets et les données personnelles avant de contacter l’assistance.