Codes d'erreur WhatsApp Cloud API : signification et solutions

Ce guide s'adresse aux développeurs et aux équipes d'exploitation de la messagerie qui constatent des échecs d'envoi WhatsApp et doivent savoir rapidement s'il faut corriger la requête, attendre, changer de type de message ou s'arrêter. Chaque code ci-dessous a été vérifié dans la référence des codes d'erreur de Meta pour Cloud API ; les codes et leur libellé évoluent, confirmez donc auprès de cette page avant de figer une logique dans votre code.

Où apparaissent les erreurs de WhatsApp Cloud API ?

Les erreurs apparaissent à deux endroits, et il faut capturer les deux. Les erreurs de requête reviennent immédiatement dans la réponse de l'API ; les erreurs de livraison arrivent plus tard dans un webhook de statut.

• Erreurs synchrones. La requête d'envoi est rejetée et la réponse contient un objet error avec code, message, type et souvent error_data.details. Exemples typiques : jetons expirés, paramètres manquants et incohérences avec le modèle.
• Erreurs asynchrones. La requête d'envoi réussit et renvoie un identifiant de message, mais un webhook ultérieur signale status: failed avec un tableau errors. Exemples typiques : fenêtres de service fermées, destinataires injoignables et limites marketing.

Une erreur fréquente consiste à ne journaliser que la réponse HTTP. L'équipe croit alors qu'une campagne a réussi parce que chaque requête a renvoyé un identifiant de message, alors que des centaines de messages ont échoué dans les webhooks. Pour comprendre la relation entre les statuts, voir envoyé, délivré, lu et échoué expliqués.

Quels sont les codes d'erreur WhatsApp les plus courants ?

Le tableau liste les codes que la plupart des équipes rencontrent, classés selon la suite à donner. Les descriptions paraphrasent la référence de Meta.

Comment corriger les erreurs à l'origine de la plupart des campagnes en échec ?

En pratique, une poignée de codes cause l'essentiel des échecs. Chacun obéit à une règle de décision claire.

131047 : la fenêtre de service est fermée

Le client a écrit pour la dernière fois il y a plus de 24 heures. Les messages texte libres, les médias et les messages interactifs ne sont autorisés que dans la fenêtre de service client de 24 heures ; au-delà, il faut utiliser un modèle approuvé ; voir la fenêtre de service client de 24 heures. Les conseillers y sont souvent confrontés en répondant à une ancienne conversation. Affichez-leur l'état de la fenêtre et proposez un sélecteur de modèles lorsqu'elle a expiré.

131026 : message non livrable

Commencez par l'hygiène des numéros : format international, indicatif pays correct, pas de zéro initial après l'indicatif. Acceptez ensuite que certains numéros ne soient tout simplement pas sur WhatsApp, ou utilisent une ancienne version de l'application. Pour les messages urgents comme les OTP, basculez sur le SMS. Voir WhatsApp, SMS et RCS.

131049 et 131050 : limites marketing et désinscriptions

Les deux concernent les messages marketing. 131050 est le choix explicite de l'utilisateur de ne plus en recevoir ; excluez ces utilisateurs du marketing et abonnez-vous au webhook de préférences utilisateur de Meta. 131049 signifie que Meta a choisi de ne pas livrer pour protéger l'engagement des utilisateurs ; Meta conseille d'attendre au moins 24 heures, et des relances plus rapprochées échoueront probablement encore. Réduisez la fréquence et améliorez la pertinence plutôt que de renvoyer.

130429, 131048 et 131056 : envoyer trop vite ou trop

130429 est une limite de débit : mettez les messages en file d'attente et appliquez un backoff. 131056 se joue au niveau de la paire : vous écrivez trop souvent à une même personne. 131048 est un signal de qualité sur le numéro expéditeur et appelle une correction du contenu et du ciblage, pas une relance. Voir limites de messagerie et note de qualité.

132000, 132001 et 132012 : incohérences de modèle

Ce sont presque toujours des bogues d'intégration. Le nom du modèle, le code de langue (par exemple ar plutôt que en_US) et le nombre de variables doivent correspondre exactement à ce qui a été approuvé. Mettez en place un test qui envoie chaque modèle avec des valeurs d'exemple à chaque modification.

Une politique de relance que vous pouvez implémenter

Utilisez cette checklist pour classer chaque échec automatiquement.

1. Journalisez le code, le titre, error_data.details, l'identifiant du message, le destinataire et le nom du modèle.
2. Ne réessayez jamais 131050, 131021, 132016, 368 et 131031. Signalez immédiatement 368 et 131031 à un administrateur.
3. Corrigez, puis réessayez les erreurs d'autorisation (0, 190, 10), de paramètres (131008, 131009, 135000), de modèle (132000 à 132015) et de facturation (131042). Alertez l'équipe responsable.
4. Appliquez un backoff puis réessayez pour 130429, 4, 80007, 131016 et 131057, avec un backoff exponentiel plafonné.
5. Changez de canal ou de type de message pour 131047 (modèle) et 131026 (SMS ou e-mail).
6. Attendez 24 heures ou plus pour 131049 et revoyez la fréquence des campagnes.
7. Reportez les échecs par code dans les rapports de campagne, et non sous un seul total « échec ».

Exemple concret : la promotion en échec d'un distributeur de Riyad

Exemple fictif. « Najd Home » envoie un modèle marketing à 20 000 clients ayant donné leur consentement (opt-in). L'API accepte chaque requête, mais les webhooks de statut font apparaître environ 1 400 échecs.

Une fois regroupée par code, la situation est claire. Le plus gros groupe est 131049 : l'équipe retire ces utilisateurs des deux envois suivants et réduit la fréquence hebdomadaire. Un groupe plus petit relève de 131026 ; l'analyse montre que de nombreux numéros sont enregistrés avec un zéro initial local, ce qu'une correction de normalisation résout. Plusieurs utilisateurs en 131050 sont exclus définitivement du marketing. Quelques erreurs 130429 venaient de la rafale initiale ; l'envoi est désormais cadencé par une file d'attente.

Erreurs courantes et limites assumées

• Considérer chaque échec comme réessayable. Cela gaspille du budget et peut dégrader la qualité.
• Figer les textes de Meta dans le code. Meta met à jour titres et descriptions ; appuyez la logique sur le code numérique et tenez une table de correspondance que vous pouvez mettre à jour.
• Ignorer error_data.details. Il désigne souvent le paramètre fautif exact.
• Tout échec n'a pas de solution. Certains destinataires ne sont pas joignables sur WhatsApp, et Meta n'explique pas chaque décision 131049. Prévoyez un canal alternatif.

Comment OmniChannels.ai vous accompagne

OmniChannels.ai, propulsé par BroadNet Technologies, met à disposition des rapports de livraison en vues synthétique et avancée, avec filtres et export CSV, pour analyser les messages en échec par campagne. Le repli entre canaux peut renvoyer le message par RCS ou SMS en cas d'échec sur WhatsApp, et les modèles sont prévisualisés sur une maquette de téléphone et suivis jusqu'à leur approbation, ce qui réduit les erreurs d'incohérence. Les webhooks remontent les statuts FAILED et REJECTED dans un format normalisé unique, et la documentation développeurs publique comprend une référence des erreurs et limites.