Pourquoi un message WhatsApp a échoué : lire le statut failed et ses erreurs
Un webhook de statut failed signifie que Meta n'a pas pu envoyer ni livrer un message envoyé par l'entreprise via l'API. Il arrive sur le champ messages avec status failed et un tableau errors contenant code, title, message, error_data.details et href. Le code indique la raison : 131047 fenêtre fermée, 131026 non livrable, 131049 limite marketing, 131050 marketing arrêté, 131042 problème de paiement.
easyCoexistence connecte le numéro de votre application WhatsApp Business à la Cloud API de Meta via Coexistence, et transmet les statuts failed à votre serveur, directement ou sous forme de transferts signés lorsque les automatisations sont activées.
Plus de 24 heures se sont écoulées depuis la dernière réponse du destinataire ; la solution de Meta est d'envoyer un template à la place.
Non livré afin de préserver l'engagement de l'écosystème ; attendez au moins 24 heures avant de renvoyer le template marketing.
Le destinataire a choisi d'arrêter les messages marketing de l'entreprise ; Meta indique de ne pas réessayer.
Un statut failed n'inclut pas le tableau contacts ; rapprochez l'échec grâce à statuses.id.
Meta facture les messages lorsqu'ils sont livrés, et non lorsqu'ils sont envoyés.
À quoi ressemble un statut failed ?
Comme tout statut, avec en plus errors. Le tableau contacts est absent, recipient_user_id est omis lorsque le message a été envoyé à un numéro de téléphone, et il n'y a pas d'objet pricing. title et message reprennent le même texte, error_data.details l'explique en une phrase, et href renvoie vers la liste des codes d'erreur de Meta. Voici l'exemple de Meta lui-même, un template marketing arrêté par la limite par utilisateur :
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
"status": "failed",
"timestamp": "1751142888",
"recipient_id": "16505551234",
"errors": [
{
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement.",
"message": "This message was not delivered to maintain healthy ecosystem engagement.",
"error_data": {
"details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
},
"href": "/documentation/business-messaging/whatsapp/support/error-codes"
}
]
}
]
},
"field": "messages"
}
]
}
]
}Quels sont les codes d'erreur les plus fréquents, et que signifient-ils ?
Meta renvoie les erreurs dans la réponse d'envoi, dans un statut failed, ou dans les deux, si bien que le même code peut vous parvenir de l'une ou l'autre façon ; votre gestionnaire doit donc lire les deux emplacements. Voici les codes qui expliquent la plupart des messages qui n'arrivent jamais, avec la raison donnée par Meta et la première chose à essayer ; la liste complète se trouve dans la référence des codes d'erreur de Meta :
Comment un gestionnaire doit-il réagir à chaque type d'échec ?
Classez le code selon ce qu'il faut faire ensuite, avant toute nouvelle tentative. Une relance générale transforme un désabonnement aux messages marketing en échecs répétés et peut prolonger un blocage, tandis que l'abandon d'une erreur temporaire fait perdre un message qui serait passé une minute plus tard.
- Réessayer avec un délai croissant : 131000 inconnu, 131016 service indisponible, 130429 débit atteint.
- Attendre d'abord : 131049, au moins 24 heures, car des tentatives trop précoces peuvent bloquer cet utilisateur jusqu'à 24 heures de plus.
- Changer de message : 131047 exige un template approuvé, car la fenêtre de 24 heures est fermée.
- Arrêter pour ce client : 131050, jusqu'à réception d'un
user_preferencesresume. - Corriger le compte ou le contenu : 131042 paiement, 131031 compte restreint, 131053 média.
Quels échecs n'apparaissent que sous forme de statut failed ?
Ceux que Meta décide après avoir accepté la requête. L'envoi renvoie un wamid, et le refus arrive plus tard sur ce webhook. Meta ne livre pas les templates marketing aux utilisateurs WhatsApp disposant d'un numéro de téléphone américain (+1 avec un indicatif régional américain), un template marketing envoyé à un client ayant cessé les messages marketing est traité puis signalé comme échoué avec 131050, et la limite marketing par utilisateur signale 131049 de la même manière.
Si le numéro n'a pas de destination webhook, ces échecs n'apparaissent nulle part et le message semble simplement envoyé. Pour l'ordre complet des vérifications lorsqu'un client n'a rien reçu, consultez la page sur les messages WhatsApp API non livrés.
Que change un numéro en Coexistence ?
Deux points comptent. D'abord, la fenêtre de 24 heures ne s'applique qu'à l'API. Le guide Coexistence de Meta indique que les messages envoyés depuis l'application WhatsApp Business ne sont pas soumis à la fenêtre du service client ; ainsi, après un 131047, le propriétaire peut toujours répondre à ce client depuis son téléphone, tandis que votre système envoie un template approuvé.
Ensuite, le débit est fixe. Un numéro utilisé à la fois dans l'application et dans l'API envoie au maximum 20 messages par seconde, et dépasser ce seuil renvoie 130429. Tout le reste se lit comme sur n'importe quel numéro Cloud API : même champ, même tableau errors, mêmes codes.
Comment les automatisations et votre IA voient-elles un échec ?
Tout dépend du moment où Meta refuse. Un refus à l'envoi, comme 131047, fait échouer l'étape de l'automatisation : l'exécution affiche Failed avec le message de Meta dans l'onglet Runs, et le propriétaire reçoit un e-mail pour répondre lui-même à ce client. Les automatisations vérifient aussi la fenêtre avant d'envoyer une réponse en texte libre et passent avec window_closed au lieu d'essayer.
Un échec signalé par Meta après coup arrive sous forme de statut failed sur votre URL de transfert ou votre destination directe, et l'exécution reste en l'état. Une IA qui a envoyé un template via le connecteur MCP voit le wamid et « sent : true » ; demandez à votre système le statut de ce wamid, ou demandez à l'assistant d'exécuter get_number_health lorsque beaucoup de messages échouent en même temps.
Erreurs courantes
- Relancer 131050 en boucle. Le client a cessé les messages marketing, donc chaque tentative échoue de la même façon jusqu'à ce qu'il les réactive.
- Renvoyer un template marketing 131049 dans les heures qui suivent. Meta demande au moins 24 heures, et des tentatives trop précoces peuvent bloquer cet utilisateur jusqu'à 24 heures de plus.
- Ne journaliser que le title. error_data.details contient la raison précise ; stockez donc le code et les détails ensemble, avec le wamid.
- Fonctionner sans destination webhook et juger de la livraison à partir de la réponse d'envoi, qui indique seulement que Meta a accepté le message.
Quand la réponse d'une automatisation est refusée à l'envoi, l'exécution affiche l'erreur de Meta et vous recevez un e-mail, et chaque numéro est surveillé 24/7 pour détecter les déconnexions et les baisses de qualité. De US$ 9 à US$ 0,75 par numéro et par mois, en baisse à mesure que vous ajoutez des numéros, avec un essai gratuit de 3 jours.
Questions fréquemment posées
Meta facture-t-il un message en échec ?
Les pages tarifaires de Meta indiquent qu'il facture les messages livrés, et non les messages seulement envoyés. Un statut failed ne contient aucun objet pricing. Les frais sont imputés au compte WhatsApp Business de l'entreprise ; easyCoexistence n'y applique jamais de majoration.
Le code 131026 signifie-t-il que le client a bloqué l'entreprise ?
La liste de Meta pour 131026 cite d'autres raisons : le numéro n'est pas sur WhatsApp, le destinataire n'a pas accepté les dernières conditions, ou sa version de WhatsApp est trop ancienne. Meta conseille de demander au client, par un autre canal, de vérifier ces points.
Pourquoi recipient_user_id apparaît-il sur certains échecs et pas sur d'autres ?
Meta l'omet dans un statut failed lorsque le message a été envoyé à un numéro de téléphone. Lorsque vous avez envoyé au BSUID du client, l'échec le contient, et c'est recipient_id qui peut manquer.
Un message peut-il échouer après avoir été livré ?
La référence de Meta décrit failed comme un échec d'envoi ou de livraison. Une fois le message parvenu à l'appareil, les statuts suivants attendus sont « read », ou « played » pour les messages vocaux.
Poursuivre la lecture
Prêt à commencer ?
Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.
Commencer l'essai gratuitVérifié le