Errore WhatsApp 3: capacità o autorizzazione mancante
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
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).
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:
| Codice | Formulazione di Meta | Cosa manca |
|---|---|---|
| 0 | "We were unable to authenticate the app user." | Un utente autenticabile dietro il token |
| 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 | "Permission is either not granted or has been removed." | Un'autorizzazione, o l'idoneità per l'API chiamata |
| 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_managementewhatsapp_business_messaging(Meta, WhatsApp support). - 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);
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
Ispeziona il token nel
debugger dei token di accesso: a quale
app appartiene, e porta whatsapp_business_management e whatsapp_business_messaging?
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).
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: autorizzazione non concessa o rimossa, oppure API non idonea.
- 200: nessun token, oppure un utente senza accesso all'account.
- 190: il token è scaduto.
- 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
Errore WhatsApp 0: impossibile autenticare — soluzione
Errore WhatsApp 0 "We were unable to authenticate the app user": token scaduto o invalidato, oppure accesso revocato. Come risolverlo, e il caso di Genuka WA.
Errore WhatsApp 10: autorizzazione negata — causa e soluzione
Errore WhatsApp 10: un'autorizzazione mancante, un modello OTP su un'azienda non verificata, oppure "Paid Message Account" quando il numero è passato a un altro account WhatsApp Business.