# Erreur WhatsApp 3 : capacité ou permission manquante

URL: https://wa.genuka.com/docs/errors/3
Language: French

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#authorization-errors)

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](https://developers.facebook.com/docs/graph-api/guides/error-handling)).

### 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#authorization-errors) :

| Code                    | Libellé Meta                                              | Ce qui manque                                             |
| ----------------------- | --------------------------------------------------------- | --------------------------------------------------------- |
| [0](https://wa.genuka.com/docs/errors/0)     | « We were unable to authenticate the app user. »          | Un utilisateur authentifiable derrière le jeton           |
| [190](https://wa.genuka.com/docs/errors/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](https://wa.genuka.com/docs/errors/10)   | « Permission is either not granted or has been removed. » | Une permission, ou l'éligibilité à l'API appelée          |
| [200](https://wa.genuka.com/docs/errors/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support#authentication-authorization)).
* **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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#marketing-messages-api-for-whatsapp-error-codes)) ;
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

1. **Inspectez le jeton** dans le
   [débogueur de jetons](https://developers.facebook.com/tools/debug/accesstoken/) : à quelle app
   appartient-il, et porte-t-il `whatsapp_business_management` et `whatsapp_business_messaging` ?
2. **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](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens#system-user-access-tokens)).
3. **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](https://wa.genuka.com/docs/errors/10) : permission non accordée ou retirée, ou API non éligible.
* [200](https://wa.genuka.com/docs/errors/200) : jeton absent, ou utilisateur sans accès au compte.
* [190](https://wa.genuka.com/docs/errors/190) : le jeton a expiré.
* [0](https://wa.genuka.com/docs/errors/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.

## Sources

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Graph API, Handling errors](https://developers.facebook.com/docs/graph-api/guides/error-handling)
* [Meta — WhatsApp support](https://developers.facebook.com/documentation/business-messaging/whatsapp/support)
* [Meta — Access tokens](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens)