Genuka WA docs

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:

CodiceFormulazione di MetaCosa 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_management e whatsapp_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à.

CanaleCosa ricevi
POST /api/v1/messages409, "error": "send_config", meta.code: 3
POST /api/v1/templates403, "error": "meta_rejected", meta.code: 3
Campagna MARKETINGSe 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

In questa pagina