Codes d'erreur WhatsApp Cloud API : causes et solutions

Codes d'erreur de l'API WhatsApp Cloud : ce que signifient 131047, 131026, 130429, 132001, 141010 et les autres, et s'il faut réessayer.

Un code d'erreur WhatsApp est le numéro que Meta renvoie quand la Cloud API refuse un appel ou ne parvient pas à remettre un message. Avec Genuka WA, vous le lisez dans le champ meta.code de la réponse d'erreur, ou dans data.errors[].code du webhook de statut failed. Les tableaux ci-dessous donnent, pour chaque code, sa signification et s'il faut réessayer.

Mis à jour le 8 octobre 2026

Quels codes d'erreur WhatsApp sont documentés ici ?

Les familles suivent celles de la liste officielle de Meta (autorisation, limites de débit, intégrité, autres erreurs), et les « autres erreurs » sont regroupées ici par sujet. Les messages de Meta sont cités tels quels, en anglais, comme ils arrivent dans les réponses de l'API.

Autorisation et jetons d'accès

Code	Message de Meta	Ce que ça veut dire	Réessayer ?
0	"We were unable to authenticate the app user."	Le jeton d'accès a expiré, a été invalidé, ou son propriétaire a coupé l'accès des applications.	Non : il faut un nouveau jeton. Avec Genuka WA, il est de notre côté : contactez le support.
3	"Capability or permissions issue."	L'application n'a pas la capacité ou la permission exigée par cet endpoint précis.	Non : accorder la permission manquante.
10	"Permission is either not granted or has been removed."	Une permission manque. Cas fréquent : un template OTP pour une entreprise non vérifiée par Meta.	Non.
190	"Your access token has expired."	Le jeton d'accès a expiré ou n'est plus valide.	Non : remplacer le jeton. Avec Genuka WA, vous ne manipulez aucun jeton Meta.
200	"Permission is either not granted or has been removed." (plage 200 à 299)	Jeton absent, permission retirée, ou utilisateur système sans accès au compte. Rien à voir avec le statut HTTP 200.	Non : rendre l'accès.

Limites de débit

Code	Message de Meta	Ce que ça veut dire	Réessayer ?
4	"The app has reached its API call rate limit."	L'application entière a dépassé sa limite d'appels à l'API de Meta.	Oui, plus tard, en réduisant le volume d'appels.
80007	"The WhatsApp Business Account has reached its rate limit."	Trop d'appels de gestion (templates, numéros) sur un même compte WhatsApp Business dans l'heure.	Oui, plus tard.
130429	"Cloud API message throughput has been reached."	Le numéro dépasse son débit d'envoi de messages.	Oui, avec un délai croissant.
131048	"Message failed to send because there are restrictions on how many messages can be sent from this phone number…"	Meta restreint les envois du numéro après trop de blocages ou de signalements spam.	Plus tard seulement, après avoir assaini vos envois.
131056	"Too many messages sent from the sender phone number to the same recipient phone number in a short period of time."	Trop de messages au même destinataire en peu de temps.	Oui, vers ce destinataire, après une pause.

Intégrité et état du compte

Code	Message de Meta	Ce que ça veut dire	Réessayer ?
368	"The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy."	Le compte WhatsApp Business est restreint ou désactivé pour violation d'une règle de Meta.	Non : demander un réexamen à Meta.
141010	"The Business has not passed business verification"	L'entreprise n'a pas passé la vérification Meta : ses templates OTP sont refusés. Ce code apparaît dans l'état de santé (`health_status`) du compte, pas dans la liste des codes d'erreur de Meta.	Non : faire vérifier l'entreprise.

Requête et numéro

Code	Message de Meta	Ce que ça veut dire	Réessayer ?
33	"The business phone number has been deleted."	L'identifiant de numéro utilisé ne pointe plus sur un numéro actif.	Non : vérifier l'identifiant, reconnecter le numéro.
100	"The request included one or more unsupported or misspelled parameters."	Un paramètre est inconnu, mal orthographié ou trop long. La cause est en général dans `details`.	Non : corriger la requête.

Remise du message et paiement

Code	Message de Meta	Ce que ça veut dire	Réessayer ?
131026	"Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp phone number…"	Le destinataire n'est pas sur WhatsApp, n'a pas accepté les conditions d'utilisation, ou son application est trop ancienne.	Non : vérifier le numéro, passer par un autre canal.
131042	"There was an error related to your payment method."	Le compte WhatsApp Business n'a pas de moyen de paiement valide chez Meta, qui facture le client directement.	Après avoir ajouté ou corrigé le moyen de paiement chez Meta.
131047	"More than 24 hours have passed since the recipient last replied to the sender number."	La fenêtre de service de 24 heures est fermée : seul un template approuvé peut encore partir.	Non : renvoyer le contenu sous forme de template.
131049	"This message was not delivered to maintain healthy ecosystem engagement."	Meta a retenu un template marketing, le plus souvent parce que le destinataire a atteint sa limite marketing.	Pas avant 24 heures (les numéros américains sont un cas à part, voir la page).
131050	"Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business."	Le destinataire a arrêté vos messages marketing.	Jamais.

Templates et Flows

Code	Message de Meta	Ce que ça veut dire	Réessayer ?
132000	"The number of variable parameter values included in the request did not match the number of variable parameters defined in the template."	Le nombre de valeurs envoyées ne correspond pas au nombre de variables du template.	Non : envoyer une valeur par variable.
132001	"The template does not exist in the specified language or the template has not been approved."	Aucun template approuvé de ce nom dans cette langue. Piège fréquent : `en` et `en_US` sont deux templates différents.	Non : vérifier le nom, la langue et le statut.
132015	"Template is paused due to low quality so it cannot be sent in a template message."	Meta a mis le template en pause pour mauvaise qualité.	Après la levée de la pause, ou avec un autre template.
132069	"Flow is in throttled state and 10 messages using this flow were already sent in the last hour."	Le Flow est limité à 10 envois par heure parce que son endpoint répond mal.	Après avoir réparé l'endpoint.

Où lire le code d'erreur dans Genuka WA ?

À deux endroits, selon le moment où Meta refuse.

Pendant l'appel. Quand Meta refuse la requête, la réponse d'erreur de Genuka WA porte un objet meta : le code de Meta, sa classe, retryable qui dit si un nouvel essai a un sens, et traceId, l'identifiant que demande le support de Meta. Exemple tiré de la référence de l'API :

422 — refusé par Meta

{
  "error": "meta_rejected",
  "message": "Invalid parameter",
  "meta": {
    "errorClass": "template",
    "retryable": false,
    "code": 100,
    "details": "body_text example count does not match the number of variables",
    "traceId": "AbC…"
  }
}

Après l'envoi. Un message accepté peut encore échouer à la remise (131026, 131049, 131050…). L'échec arrive alors sur vos webhooks : événement message_status, statut failed, et le code de Meta dans data.errors :

Webhook message_status (extrait)

{
  "type": "message_status",
  "field": "messages",
  "connection_id": "con_1",
  "data": {
    "id": "wamid.HBgLMjM3...",
    "status": "failed",
    "recipient_id": "237690000001",
    "errors": [{ "code": 131026, "title": "…", "message": "…" }]
  }
}

Mon code n'est pas dans cette liste : où chercher ?

Meta publie la liste complète des codes de la Cloud API, avec la solution qu'il suggère pour chacun : codes d'erreur de la Cloud API. Le champ meta.details reprend le détail donné par Meta pour votre requête. Si le refus reste incompréhensible, transmettez au support meta.traceId et l'en-tête x-request-id de la réponse.

FAQ

Quelle différence entre les erreurs 4, 80007 et 130429 ?

Elles ne limitent pas la même chose. L'erreur 4 vise les appels de l'application entière, 80007 les appels de gestion sur un compte WhatsApp Business (templates, numéros), et 130429 le débit d'envoi de messages d'un numéro. Les trois se réessaient plus tard, avec un délai croissant.

Faut-il réessayer automatiquement une erreur WhatsApp ?

Seulement quand meta.retryable vaut true, et avec un délai croissant. Les erreurs d'autorisation, de template ou de destinataire échouent à l'identique tant que leur cause n'est pas corrigée. Cas particulier : 131048 est marquée réessayable, mais cela signifie « plus tard », pas « tout de suite ».

Meta — Error codes (Cloud API)
Meta — Health status