# Errore WhatsApp 3: capacità o autorizzazione mancante

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

> Errore 3 della WhatsApp Cloud API (Capability or permissions issue): in cosa si distingue dagli errori 0, 10, 190 e 200, e come risolverlo.

L'errore WhatsApp 3 significa che all'applicazione che chiama la Cloud API manca la capacità o
l'autorizzazione richiesta da questo specifico endpoint. Il token può essere perfettamente valido: è
l'app a non essere autorizzata a fare quella particolare chiamata. Si risolve concedendo
l'autorizzazione o la funzionalità mancante, mai inviando di nuovo la stessa richiesta.

## Cosa significa l'errore 3?

Meta lo elenca tra gli errori di autorizzazione della Cloud API:

> "Capability or permissions issue."
> — [Meta, Cloud API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#authorization-errors)

La soluzione suggerita: verificare nel debugger dei token di accesso che all'app siano state
concesse le autorizzazioni richieste dall'endpoint. La documentazione generale della Graph API
chiama questo codice "API Method" e lo riassume così: "Make sure your app has the necessary
capability or permissions to make this call"
([Meta, Graph API error handling](https://developers.facebook.com/docs/graph-api/guides/error-handling)).

### Come lo distingui dagli altri errori di autorizzazione?

I sei codici di autorizzazione della Cloud API rispondono ciascuno a una domanda diversa. La
formulazione è quella della
[pagina degli errori di Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#authorization-errors):

| Codice                     | Formulazione di Meta                                    | Cosa manca                                                    |
| -------------------------- | ------------------------------------------------------- | ------------------------------------------------------------- |
| [0](https://wa.genuka.com/it/docs/errors/0)     | "We were unable to authenticate the app user."          | Un utente autenticabile dietro il token                       |
| [190](https://wa.genuka.com/it/docs/errors/190) | "Your access token has expired."                        | Un token ancora valido                                        |
| **3**                      | "Capability or permissions issue."                      | Una capacità o un'autorizzazione dell'app per questo endpoint |
| [10](https://wa.genuka.com/it/docs/errors/10)   | "Permission is either not granted or has been removed." | Un'autorizzazione, o l'idoneità per l'API chiamata            |
| [200](https://wa.genuka.com/it/docs/errors/200) | "No access token was provided."                         | Un token nella richiesta                                      |
| Da 200 a 299               | "Permission is either not granted or has been removed." | Un'autorizzazione, o l'accesso dell'utente all'account        |

Tieni a mente il confine: con 0 e 190 è il token stesso a essere morto; con 200 ("No access token
was provided") il token non c'è proprio; con 3, 10 e da 201 a 299 il token è vivo ma non dà accesso
a ciò che stai chiedendo.

## Quando si verifica l'errore 3?

* **Il token è stato generato senza le autorizzazioni WhatsApp**, oppure per un'app diversa da
  quella che fa la chiamata. Al momento della generazione, Meta ti chiede di selezionare l'app usata
  per le chiamate e le autorizzazioni `whatsapp_business_management` e `whatsapp_business_messaging`
  ([Meta, WhatsApp support](https://developers.facebook.com/documentation/business-messaging/whatsapp/support#authentication-authorization)).
* **L'endpoint appartiene a una funzionalità che l'app o l'account non ha attivato.** La Marketing
  Messages API ne è un esempio: richiede un onboarding completato da un utente del portfolio con
  controllo completo (stessa pagina). Finché quell'onboarding non è fatto, la chiamata non ha motivo
  di riuscire.

### Dove lo vedi in Genuka WA?

Genuka WA colloca il codice 3 nella classe `config`: un problema di token, di autorizzazione o di
registrazione che un nuovo tentativo non risolverà.

| Canale                   | Cosa ricevi                                                                                                                                                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/v1/messages`  | `409`, `"error": "send_config"`, `meta.code: 3`                                                                                                                                                                                                             |
| `POST /api/v1/templates` | `403`, `"error": "meta_rejected"`, `meta.code: 3`                                                                                                                                                                                                           |
| Campagna `MARKETING`     | Se la Marketing Messages API rifiuta l'invio con un errore 4xx di autorizzazione o di parametro (codici 3, 10, 100…), Genuka invia di nuovo il messaggio tramite l'endpoint `/messages` standard; se rifiuta anche quello, il destinatario passa a `failed` |

L'ultimo caso è voluto. Meta non espone alcun indicatore che dica in anticipo se un account ha
accesso alla Marketing Messages API: Genuka la prova, tratta un rifiuto 4xx di tipo autorizzazione
come "funzionalità non disponibile su questo account" e invia di nuovo il messaggio per la via
standard. Il ripiego è silenzioso: viene registrato solo il risultato dell'invio su `/messages`. Non
copre tutti i rifiuti: Meta segnala la mancata idoneità anche con il codice `134102` e uno stato
HTTP 500
([Meta, Marketing Messages API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#marketing-messages-api-for-whatsapp-error-codes));
Genuka lo tratta come un'interruzione temporanea, lo riprova, poi segna il destinatario come
`failed`.

## Come risolvo l'errore 3?

### Se chiami la Cloud API con il tuo token

1. **Ispeziona il token** nel
   [debugger dei token di accesso](https://developers.facebook.com/tools/debug/accesstoken/): a quale
   app appartiene, e porta `whatsapp_business_management` e `whatsapp_business_messaging`?
2. **Rigeneralo se necessario**, selezionando l'app giusta ed entrambe le autorizzazioni WhatsApp. Per
   un servizio in produzione, preferisci un token di utente di sistema
   ([Meta, Access tokens](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens#system-user-access-tokens)).
3. **Controlla i requisiti della funzionalità che stai chiamando.** Se l'endpoint appartiene a una
   funzionalità che richiede un onboarding o un'idoneità, come la Marketing Messages API, completa
   prima quel passaggio e poi riprova.

### Se passi da Genuka WA

Non hai nessun token Meta da correggere: un codice 3 su un invio o sulla creazione di un modello è
compito di Genuka. Contatta il supporto con l'header `x-request-id` della risposta e il
`meta.traceId`. Se stai inviando un tipo di messaggio avanzato tramite il campo `raw`, dillo: è lì
che una funzionalità non attivata ha più probabilità di emergere.

## Come prevengo l'errore 3?

* **Genera ogni token per l'app giusta**, con le sole autorizzazioni WhatsApp che ti servono.
* **Prima di adottare una nuova funzionalità di Meta**, leggi i suoi requisiti di accesso: molte
  richiedono un onboarding o un'idoneità propri.
* **Imposta gli avvisi sulla classe `config`**, non sul testo del messaggio: Meta avverte che i
  titoli degli errori verranno prima o poi deprecati.

## Codici di errore correlati

* [10](https://wa.genuka.com/it/docs/errors/10): autorizzazione non concessa o rimossa, oppure API non idonea.
* [200](https://wa.genuka.com/it/docs/errors/200): nessun token, oppure un utente senza accesso all'account.
* [190](https://wa.genuka.com/it/docs/errors/190): il token è scaduto.
* [0](https://wa.genuka.com/it/docs/errors/0): Meta non è riuscita ad autenticare l'utente dell'app.

## FAQ

### Qual è la differenza tra l'errore 3 e l'errore 10?

Meta collega il 3 a una capacità o autorizzazione mancante per l'endpoint, e il 10 a
un'autorizzazione non concessa o rimossa, anche quando l'account non è idoneo per l'API chiamata. In
entrambi i casi il token è vivo; è ciò che autorizza a non bastare.

### Devo riprovare una chiamata rifiutata con l'errore 3?

No. Finché manca l'autorizzazione o la funzionalità, la stessa richiesta fallirà allo stesso modo.

### Un destinatario di una campagna di marketing può fallire con l'errore 3?

Sì. Un rifiuto della sola Marketing Messages API non ti raggiunge mai: Genuka invia di nuovo il
messaggio tramite `/messages`, ed è quel secondo invio a contare. Se il destinatario passa comunque
a `failed` con un motivo di autorizzazione, anche `/messages` l'ha rifiutato: il problema riguarda
il numero, non solo la Marketing Messages API, ed è da sottoporre al supporto Genuka.

## Fonti

* [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)
