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 :
{
"error": {
"code": "invalid_phone",
"message": "Le champ « to » doit être un numéro au format international, indicatif pays compris (exemple : +237699001122)."
}
}
codeest stable : c'est lui que votre code doit tester.messageest écrit pour un humain, en français, et peut évoluer.detailsapporte des précisions quand c'est utile, par exemple la liste des champs invalides :
{
"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(sauf429) ne se corrigent pas en réessayant : corrigez d'abord la requête. - Pour
429et503, réessayez après un délai croissant (par exemple 2, 4, puis 8 secondes). - Pour
POST /v1/messages, ajoutez un en-têteIdempotency-Key: un nouvel essai ne créera pas de doublon. Voir Messages.