Erreur 131030 et autres codes WhatsApp API : guide de résolution complet

Lorsque vous travaillez avec l'API WhatsApp Business, les erreurs font partie du quotidien. Chaque code d'erreur raconte une histoire précise sur ce qui s'est passé. Comprendre ces codes et savoir y répondre rapidement est une compétence essentielle pour toute équipe technique ou marketing qui pilote des envois WhatsApp. Ce guide de référence couvre les erreurs les plus fréquentes et leurs solutions.

La structure des erreurs WhatsApp API

L'API WhatsApp Business Cloud retourne les erreurs dans un format JSON standardisé :

{
  "error": {
    "message": "Message descriptif de l'erreur",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "Titre visible",
    "error_user_msg": "Message pour l'utilisateur",
    "fbtrace_id": "ID de trace Meta"
  }
}

Le champ code (et parfois error_subcode) est le plus important pour le diagnostic. Meta distingue plusieurs familles d'erreurs : les erreurs d'authentification (codes 100-200), les erreurs de limitation de débit (codes 130xxx), les erreurs de message (codes 131xxx), les erreurs de registre (codes 132xxx) et les erreurs de flux (codes 133xxx).

Pour une compréhension globale des APIs WhatsApp Business, notre guide de l'API WhatsApp Business pose les fondamentaux. Et pour les stratégies d'automatisation qui doivent gérer ces erreurs, l'article sur les flows d'automatisation WhatsApp est complémentaire.

Les erreurs 131xxx : erreurs de message

Ce sont les erreurs les plus fréquentes en production. Voici les principales.

Erreur 131030 — Business number not able to send message C'est souvent la plus cryptique. Elle signifie que votre numéro WhatsApp Business n'est pas en mesure d'envoyer le message demandé. Les causes possibles :

• Le numéro n'est pas encore enregistré comme numéro Business (onboarding incomplet)
• Le numéro a été suspendu ou est en cours de vérification
• La combinaison numéro + template + paramètres est invalide
• Problème avec le Business Manager Meta associé

Solution 131030 : vérifiez dans le Meta Business Manager que votre numéro est bien en statut "Connected" et que le Business Manager est correctement configuré. Si la suspension est récente, attendez et contactez le support Meta.

Erreur 131026 — Recipient phone number not in allowed list Le numéro destinataire n'est pas enregistré sur WhatsApp, ou est temporairement inaccessible. C'est la première cause de non-livraison.

Solution 131026 : utilisez la vérification de numéro avant d'envoyer. Supprimez ce numéro de vos listes actives et mettez-le en statut "Invalide" dans votre CRM.

Erreur 131047 — Re-engagement message failed Le message ne peut pas être envoyé car la fenêtre de conversation de 24h a expiré et le template utilisé n'est pas un template approuvé pour les messages proactifs.

Solution 131047 : utilisez uniquement des templates approuvés de catégorie "Utility" ou "Marketing" pour les messages proactifs. Les messages textes libres ne sont possibles que dans une fenêtre de 24h après le dernier message du contact.

Les erreurs 130xxx : limitations de débit

Erreur 130429 — Rate limit hit Vous avez dépassé votre limite de messages par unité de temps. Cette erreur peut se produire au niveau du tier (limite journalière) ou au niveau de la fréquence par numéro destinataire.

Solution 130429 : implémentez un mécanisme de backoff exponentiel dans votre code (attendez 1s, puis 2s, puis 4s entre les réessais). Vérifiez votre tier actuel et planifiez vos campagnes en conséquence. Pour augmenter votre tier, maintenez une bonne qualité d'envoi pendant 7 jours consécutifs.

Erreur 130472 — User's number is part of an experiment Le numéro destinataire fait partie d'un groupe de contrôle dans un test A/B Meta. Meta peut parfois restreindre certaines livraisons pour ses propres tests internes.

Solution 130472 : aucune action possible de votre côté. Réessayez après 24h.

Les erreurs d'authentification (code 190)

Erreur 190 — Invalid OAuth 2.0 Access Token Votre token d'accès API a expiré ou a été révoqué. C'est une erreur fréquente qui interrompt tous les envois en cours.

Solution : régénérez votre token dans le Meta Business Manager. Dans Whakup, mettez à jour votre token dans les paramètres d'intégration. Mettez en place une alerte pour être notifié avant l'expiration du prochain token.

Erreur 200 — Permissions error L'application Meta n'a pas les permissions nécessaires pour effectuer l'action demandée.

Solution : vérifiez les permissions accordées à votre application dans le Meta Business Manager. Les permissions requises pour WhatsApp Business API incluent whatsapp_business_messaging et whatsapp_business_management.

Les erreurs 132xxx : erreurs de template

Erreur 132000 — Template not found Le template que vous essayez d'utiliser n'existe pas ou le nom est incorrect.

Solution : vérifiez le nom exact du template dans le Meta Business Manager. Les noms sont sensibles à la casse et aux underscores.

Erreur 132001 — Template hydration error Les paramètres envoyés ne correspondent pas aux variables définies dans le template (mauvais nombre de variables, mauvais format).

Solution : comparez scrupuleusement le nombre et l'ordre des variables dans votre appel API avec ceux définis dans le template. Un template avec 3 variables {{1}}, {{2}}, {{3}} nécessite exactement 3 paramètres dans l'ordre correct.

---

FAQ

Où trouver la liste complète des codes d'erreur WhatsApp API ? La référence officielle est disponible dans la documentation Meta for Developers : developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes. Elle est mise à jour régulièrement. Pour la gestion des erreurs dans vos automations, Whakup expose également ces codes dans ses logs détaillés.

L'erreur 131030 est-elle grave ? Peut-elle entraîner une suspension ? L'erreur 131030 est en général une erreur temporaire liée à la configuration, pas à un comportement abusif. Elle ne déclenche pas en elle-même une suspension. Cependant, si elle persiste sans investigation, elle peut signaler un problème plus profond dans votre compte Meta.

Comment loguer et analyser les erreurs API en production ? Configurez dans votre outil d'automatisation (Make, Zapier, n8n) une route d'erreur qui capture le code d'erreur et le numéro concerné, les stocke dans un Google Sheet ou une base de données, et envoie une alerte si le même code d'erreur apparaît plus de X fois en 1 heure.

Les erreurs API sont-elles différentes selon l'API Cloud et l'API On-Premise ? Il existe quelques différences dans les codes d'erreur entre les deux versions. L'API Cloud (Meta-hébergée) et l'API On-Premise (hébergée localement) ont des réponses légèrement différentes. Dans le contexte de Whakup, c'est l'API Cloud qui est utilisée — tous les codes décrits dans cet article s'y appliquent.

Mon équipe reçoit des erreurs 131030 sporadiques depuis une mise à jour. Que faire ? Les erreurs sporadiques sont souvent liées à des timeouts temporaires côté Meta ou à des conditions de réseau. Implémentez un mécanisme de retry avec backoff (3 tentatives maximum avec un délai croissant) et loguez les cas où les 3 tentatives échouent pour analyse approfondie.

---

Gérez vos erreurs API WhatsApp de manière proactive avec les bons outils. Créez votre compte Whakup et accédez aux logs d'erreur détaillés pour diagnostiquer et résoudre vos problèmes en temps réel.