Erreur WhatsApp 3 : capacité ou permission manquante

Erreur WhatsApp 3 (Capability or permissions issue) sur la Cloud API : ce qui la distingue des erreurs 0, 10, 190 et 200, et comment la corriger.

L'erreur WhatsApp 3 signifie que l'application qui appelle la Cloud API n'a pas la capacité ou la permission exigée par cet endpoint précis. Le jeton peut être parfaitement valide : c'est l'app qui n'a pas le droit de faire cet appel-là. Elle se corrige en accordant la permission ou la fonction manquante, jamais en renvoyant la même requête.

Que signifie l'erreur 3 ?

Meta la classe parmi les erreurs d'autorisation de la Cloud API :

« Capability or permissions issue. » — Meta, codes d'erreur de la Cloud API

La solution proposée : vérifier dans le débogueur de jetons que l'app a reçu les permissions exigées par l'endpoint. La documentation générale de Graph nomme ce code « API Method » et le résume ainsi : « Make sure your app has the necessary capability or permissions to make this call » (Meta, Graph API, gestion des erreurs).

Comment la distinguer des autres erreurs d'autorisation ?

Les six codes d'autorisation de la Cloud API répondent chacun à une question différente. Les libellés sont ceux de la page d'erreurs de Meta :

Code	Libellé Meta	Ce qui manque
0	« We were unable to authenticate the app user. »	Un utilisateur authentifiable derrière le jeton
190	« Your access token has expired. »	Un jeton encore valide
3	« Capability or permissions issue. »	Une capacité ou une permission de l'app pour cet endpoint
10	« Permission is either not granted or has been removed. »	Une permission, ou l'éligibilité à l'API appelée
200	« No access token was provided. »	Un jeton dans la requête
200 à 299	« Permission is either not granted or has been removed. »	Une permission, ou l'accès de l'utilisateur au compte

Retenez la frontière : avec 0 et 190, le jeton lui-même est mort ; avec 200 (« No access token was provided »), il manque purement et simplement ; avec 3, 10 et 201 à 299, le jeton vit mais ne donne pas accès à ce que vous demandez.

Quand l'erreur 3 apparaît-elle ?

Le jeton a été généré sans les permissions WhatsApp, ou pour une autre app que celle qui appelle. Meta demande, à la génération, de sélectionner l'app utilisée pour les appels et les permissions whatsapp_business_management et whatsapp_business_messaging (Meta, support WhatsApp).
L'endpoint relève d'une fonction que l'app ou le compte n'a pas activée. L'API Marketing Messages en est un exemple : elle demande un onboarding réalisé par un utilisateur du portefeuille qui en a le contrôle total (même page). Avant cet onboarding, l'appel n'a pas lieu d'aboutir.

Où la voir dans Genuka WA ?

Genuka WA range le code 3 dans la classe config : un problème de jeton, de permission ou d'enregistrement, que réessayer ne réglera pas.

Canal	Ce que vous recevez
`POST /api/v1/messages`	`409`, `"error": "send_config"`, `meta.code: 3`
`POST /api/v1/templates`	`403`, `"error": "meta_rejected"`, `meta.code: 3`
Campagne `MARKETING`	Si l'API Marketing Messages refuse l'envoi avec une erreur 4xx de permission ou de paramètre (codes 3, 10, 100…), Genuka renvoie le message par l'endpoint `/messages` classique ; si celui-ci refuse aussi, le destinataire passe `failed`

Le dernier cas est volontaire. Meta n'expose pas d'indicateur qui dirait à l'avance si un compte a accès à l'API Marketing Messages : Genuka la tente, traite un refus 4xx de type permission comme « fonction indisponible sur ce compte » et renvoie le message par la voie classique. Ce repli est silencieux : seul le résultat de l'envoi sur /messages est enregistré. Il ne couvre pas tous les refus : Meta signale aussi l'inéligibilité par le code 134102, avec un statut HTTP 500 (Meta, codes d'erreur de l'API Marketing Messages) ; Genuka le traite comme une panne passagère, le réessaie, puis marque le destinataire failed.

Comment corriger l'erreur 3 ?

Si vous appelez la Cloud API avec votre propre jeton

Inspectez le jeton dans le débogueur de jetons : à quelle app appartient-il, et porte-t-il whatsapp_business_management et whatsapp_business_messaging ?

Régénérez-le si besoin, en sélectionnant la bonne app et les deux permissions WhatsApp. Pour un service en production, préférez un jeton d'utilisateur système (Meta, Access tokens).

Vérifiez les conditions de la fonction appelée. Si l'endpoint appartient à une fonction qui demande un onboarding ou une éligibilité, comme l'API Marketing Messages, terminez cette démarche avant de réessayer.

Si vous passez par Genuka WA

Vous n'avez pas de jeton Meta à corriger : un code 3 sur un envoi ou une création de template relève de Genuka. Écrivez au support avec l'en-tête x-request-id de la réponse et meta.traceId. Si vous envoyez un type de message avancé par le champ raw, précisez-le : c'est là qu'une fonction non activée a le plus de chances d'apparaître.

Comment éviter l'erreur 3 ?

Générez chaque jeton pour la bonne app, avec les seules permissions WhatsApp utiles.
Avant d'adopter une nouvelle fonction de Meta, lisez ses conditions d'accès : beaucoup demandent un onboarding ou une éligibilité propres.
Alertez sur la classe config, pas sur le texte du message : Meta prévient que les titres d'erreur seront dépréciés.

Quels codes sont liés ?

10 : permission non accordée ou retirée, ou API non éligible.
200 : jeton absent, ou utilisateur sans accès au compte.
190 : le jeton a expiré.
0 : Meta n'a pas pu authentifier l'utilisateur de l'app.

FAQ

Quelle différence entre l'erreur 3 et l'erreur 10 ?

Meta associe 3 à une capacité ou une permission manquante pour l'endpoint, et 10 à une permission non accordée ou retirée, y compris quand le compte n'est pas éligible à l'API appelée. Dans les deux cas, le jeton vit ; c'est ce qu'il autorise qui ne suffit pas.

Faut-il réessayer un appel refusé avec l'erreur 3 ?

Non. Tant que la permission ou la fonction manque, la même requête échouera de la même façon.

Un destinataire de campagne marketing peut-il échouer sur l'erreur 3 ?

Oui. Un refus de la seule API Marketing Messages ne vous parvient pas : Genuka renvoie le message par /messages, et c'est ce second envoi qui compte. Si le destinataire passe malgré tout failed avec un motif de permission, /messages l'a refusé aussi : le problème touche le numéro, pas la seule API Marketing Messages, et relève du support Genuka.