Aller au contenu

Référence

Erreurs

Le format des erreurs de l'API et la liste de tous les codes, avec ce qu'il faut faire pour chacun.

Format

Une erreur renvoie un code HTTP 4xx ou 5xx et un corps de cette forme :

JSON
{
  "error": {
    "code": "invalid_phone",
    "message": "Le champ « to » doit être un numéro au format international, indicatif pays compris (exemple : +237699001122)."
  }
}
  • code est stable : c'est lui que votre code doit tester.
  • message est écrit pour un humain, en français, et peut évoluer.
  • details apporte des précisions quand c'est utile, par exemple la liste des champs invalides :
JSON
{
  "error": {
    "code": "validation_error",
    "message": "Certains champs sont manquants ou invalides.",
    "details": {
      "to": ["Le champ to est obligatoire."]
    }
  }
}

Tous les codes

HTTP Code Signification Que faire
401 missing_api_key Aucune clé d'API dans la requête. Ajoutez l'en-tête Authorization: Bearer ….
401 invalid_api_key Clé inconnue ou révoquée. Vérifiez la clé, ou créez-en une autre.
403 account_suspended Compte suspendu. Contactez le support.
422 validation_error Champ manquant ou invalide. Corrigez la requête d'après details.
422 invalid_phone Numéro mal formé. Utilisez le format international : +237699001122.
429 rate_limited Plus de 120 requêtes par minute avec cette clé. Attendez le délai indiqué par l'en-tête Retry-After.
429 otp_rate_limited Trop de codes demandés pour ce numéro. Patientez quelques minutes avant un nouveau code.
402 insufficient_balance Messages inclus épuisés et solde insuffisant. Rechargez votre solde.
503 no_sender_available Aucun numéro disponible pour envoyer maintenant. Réessayez dans quelques instants ; prévoyez un canal de secours pour les codes.
422 template_required Texte libre ou modèle non validé, sans numéro dédié. Utilisez un modèle validé, ou reliez votre numéro.
404 template_not_found Modèle inconnu. Vérifiez l'identifiant du modèle.
422 missing_variables Variables du modèle manquantes. Ajoutez les variables listées dans details.missing.
409 no_dedicated_sender Aucun numéro dédié relié. Reliez un numéro, ou n'imposez pas "sender": "dedicated".
403 shared_pool_not_allowed Votre forfait n'inclut pas les numéros Flare. Envoyez depuis votre numéro, ou changez de forfait.
404 otp_not_found Demande de code introuvable. Vérifiez l'id ou le numéro.
404 message_not_found Message introuvable. Vérifiez l'identifiant.
404 unknown_event Aucune règle active pour cet événement. Créez une règle dans l'espace client, ou vérifiez le nom de l'événement.
403 full_api_not_allowed API avancée non incluse dans votre forfait. Changez de forfait.
404 sender_not_found Numéro dédié introuvable. Vérifiez l'identifiant avec GET /v1/senders.
409 sender_not_connected Numéro dédié non connecté. Reliez-le depuis l'espace client.
404 route_not_available Opération non ouverte dans l'API avancée. Voir API avancée.
503 engine_unreachable Service d'envoi momentanément indisponible. Réessayez dans quelques instants.
404 not_found Route inexistante. Vérifiez l'adresse appelée.
405 method_not_allowed Méthode HTTP non prise en charge sur cette route. Vérifiez la méthode (GET, POST…).

Erreurs sur un message

Un message accepté (202) peut échouer plus tard. Son statut passe alors à failed, et son champ error précise pourquoi :

Code Signification
no_sender_available Aucun numéro n'a pu prendre le message à temps.
send_failed Tous les numéros essayés ont échoué.
delivery_failed WhatsApp a refusé de livrer le message.
engine_unreachable Le service d'envoi est resté indisponible.
account_suspended Le compte a été suspendu entre-temps.

Un message en échec n'est pas facturé. Vous êtes prévenu par l'événement message.failed sur vos webhooks.

Réessayer sans risque

  • Les erreurs 4xx (sauf 429) ne se corrigent pas en réessayant : corrigez d'abord la requête.
  • Pour 429 et 503, réessayez après un délai croissant (par exemple 2, 4, puis 8 secondes).
  • Pour POST /v1/messages, ajoutez un en-tête Idempotency-Key : un nouvel essai ne créera pas de doublon. Voir Messages.