Errore WhatsApp 190: token di accesso scaduto — causa e soluzione
Errore 190 della WhatsApp Cloud API (token di accesso scaduto): quale token è scaduto, come sostituirlo una volta per tutte, e perché chi usa Genuka WA non gestisce mai token Meta.
L'errore WhatsApp 190 significa che il token di accesso inviato alla Cloud API di Meta è scaduto o non è più valido. La soluzione è un nuovo token e, soprattutto, smettere di usare un token utente temporaneo: un token di utente di sistema non muore dopo qualche ora. Con Genuka WA non gestisci mai alcun token Meta.
Cosa significa l'errore 190?
Meta lo elenca tra gli errori di autorizzazione della Cloud API:
"Your access token has expired." — soluzione suggerita: "Get a new access token." — Meta, Cloud API error codes
La documentazione generale della Graph API, su cui è costruita la Cloud API, chiama lo stesso codice "Access token has expired" e documenta alcuni sottocodici (Meta, Graph API error handling):
| Sottocodice Graph | Nome di Meta | Cosa ti dice |
|---|---|---|
463 | Expired | Il token è scaduto, è stato revocato o non è comunque valido |
467 | Invalid Access Token | Il token è scaduto, è stato revocato o non è comunque valido |
460 | Password Changed | La persona che ha generato il token ha cambiato la sua password |
458 | App Not Installed | L'utente non ha effettuato l'accesso alla tua app |
Non costruire logica su quei sottocodici: la pagina degli errori WhatsApp dice che error_subcode è
deprecato e non viene più restituito dalla Graph v16.0 in poi. Il codice 190 e il campo details
bastano.
Quando si verifica l'errore 190?
- Stai usando il token di API Setup. La App Dashboard di Meta genera un nuovo token utente ogni volta che apri WhatsApp > API Setup. Meta l'ha pensato per i primi test: i token utente "expire quickly", quindi devi generarne uno nuovo ogni poche ore (Meta, Access tokens). È il motivo classico per cui un servizio funziona la mattina e fallisce il pomeriggio.
- Il token è stato invalidato. Password cambiata, app rimossa dall'utente, token revocato: Meta risponde 190 anche prima della data di scadenza.
- Sei un partner e il token di un cliente è morto. Alla fine dell'Embedded Signup, un Tech Provider riceve un token di utente di sistema di integrazione aziendale limitato a quel cliente. L'abbiamo visto smettere di funzionare non appena il cliente modifica l'accesso del partner nel suo Business Manager: Meta risponde allora 190 "Authentication Error" a ogni invio, per un numero che per il resto è in salute.
Come risolvo l'errore 190?
Se chiami la Cloud API con il tuo token
Ispeziona il token. Incollalo nel
debugger dei token di accesso di Meta:
mostra la scadenza e le autorizzazioni. Servono whatsapp_business_management e
whatsapp_business_messaging
(Meta, WhatsApp support).
Sostituisci un token utente con un token di utente di sistema. Nelle impostazioni del Business,
Utenti di sistema (in inglese, System Users): crea un utente di sistema, dagli il controllo della tua app, poi Generate
token, scegliendo l'app, una preferenza di scadenza e le autorizzazioni business_management,
whatsapp_business_management e whatsapp_business_messaging
(Meta, Access tokens).
Dagli accesso agli account. Un utente di sistema senza accesso all'account WhatsApp di destinazione non riceve più 190 ma 200: assegnagli l'account WhatsApp e l'account di messaggistica in Meta Business Suite, dalla scheda Persone (in inglese, People) di ciascun account (stessa pagina).
Conservalo come un segreto opaco. Meta avverte che il formato dei token può cambiare: nessuna lunghezza di colonna fissa, nessuna decodifica.
Se passi da Genuka WA
Non hai nulla da rigenerare. È Genuka WA a detenere l'accesso alla Cloud API: ogni chiamata sul tuo numero parte con il token di utente di sistema di Genuka, creato senza data di scadenza, e non con il token restituito dall'Embedded Signup quando il numero è stato collegato. Genuka ha fatto questa scelta proprio per evitare il caso del partner descritto sopra.
Un 190 in una risposta di Genuka WA è quindi, nella grande maggioranza dei casi, un incidente dal
lato di Genuka. Torna così:
{
"error": "send_config",
"message": "Authentication Error",
"meta": {
"errorClass": "config",
"retryable": false,
"code": 190,
"traceId": "AbC…"
}
}Alla creazione di un modello, lo stesso rifiuto torna come 403 meta_rejected con lo stesso oggetto
meta (riferimento API). In entrambi i casi:
- Non riprovare in un ciclo.
retryable: false: la stessa chiamata fallirà allo stesso modo. - Contatta il supporto Genuka con l'header
x-request-iddella risposta e ilmeta.traceId. - Non chiedere subito al cliente di ricollegarsi. Controlla prima
GET /api/v1/connections.disconnectedsignifica che Meta ha segnalato l'account come non più condiviso con Genuka, oppure eliminato, oppure che hai rilasciato tu stesso il numero. Un cliente che ha rimosso l'accesso lo ripristina tramite il link di connessione, senza occupare un nuovo slot; un numero rilasciato ha di nuovo bisogno di uno slot libero; un account eliminato, o disattivato da Meta (errore 368), non si ripristina in questo modo, e l'eventoaccount_updateinoltrato ai tuoi webhook ti dice di quale caso si tratta. Se risulta ancoraconnected, resta in contatto con il supporto Genuka.
Non confonderlo con gli errori sulla tua chiave API, che non vengono mai da Meta:
401 missing_bearer_token (nessun header) e 401 invalid_token (chiave sconosciuta o revocata),
vedi Autenticazione.
const response = await fetch("https://wa.genuka.com/api/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
connectionId: "con_1",
to: "+237690000001",
template: { name: "order_confirmation", language: "en_US", variables: ["Awa", "ORD-1042"] },
}),
});
const json = await response.json();
if (response.status === 401) {
// La tua chiave Genuka: mancante, sconosciuta o revocata. Meta non c'entra.
throw new Error(`Chiave API rifiutata: ${json.error}`);
}
if (json.meta?.code === 190 || json.meta?.code === 0) {
// Token Meta rifiutato: è dal lato di Genuka. Fermati e lancia un avviso, non riprovare.
console.error("Token Meta rifiutato", {
requestId: response.headers.get("x-request-id"),
traceId: json.meta.traceId,
});
}Come prevengo l'errore 190?
- Non andare mai in produzione con il token di API Setup. Esiste per inviare un primo messaggio di test, non per alimentare un servizio che gira tutta la notte.
- Un token di utente di sistema per ambiente, con le sole autorizzazioni WhatsApp che ti servono, conservato nel tuo gestore di segreti.
- Tieni d'occhio gli accessi revocati. Come partner, il webhook
account_updatesegnalaPARTNER_APP_UNINSTALLEDquando un cliente revoca l'autenticazione o disinstalla la tua app, ePARTNER_REMOVEDquando un account non è più condiviso con te (Meta, account_update webhook). Genuka WA inoltra questi eventi ai tuoi webhook (eventoaccount_update), ma dei due soloPARTNER_REMOVEDfa passare il numero adisconnected: dopo unPARTNER_APP_UNINSTALLED, restaconnected. - Imposta gli avvisi sulla classe, non sul testo. In Genuka WA,
meta.errorClass: "config"copre i problemi di token, autorizzazione e registrazione: serve l'intervento di una persona, e nessun nuovo tentativo li risolverà.
Codici di errore correlati
- 0: Meta non è riuscita ad autenticare l'utente dell'app; stesso rimedio.
- 200: il token è valido ma non ha accesso all'account o l'autorizzazione.
- 10: autorizzazione non concessa o rimossa.
- 3: capacità o autorizzazione mancante per questo endpoint.
FAQ
Quanto dura un token di accesso della WhatsApp Cloud API?
Dipende dal tipo. Un token utente, come quello della pagina API Setup, scade nel giro di qualche ora. Un token di utente di sistema è di lunga durata, e scegli tu la sua preferenza di scadenza quando lo generi.
Devo riprovare un invio fallito con 190?
Non finché il token non è cambiato. Lo stesso token produce lo stesso errore; riprovare ritarda solo l'avviso.
Il mio cliente deve ricollegarsi dopo un 190 su Genuka WA?
Solo se il suo numero risulta disconnected in GET /api/v1/connections perché ha rimosso
l'accesso di Genuka: l'evento account_update inoltrato ai tuoi webhook lo conferma. Un account
eliminato, o disattivato da Meta, non si ripristina ricollegandosi. Se il numero risulta ancora
connected, contatta il supporto Genuka con x-request-id e meta.traceId.
Devo rigenerare la mia chiave API Genuka?
No. La tua chiave pk_live_… autentica le tue chiamate a Genuka WA, non a Meta. Una chiave
rifiutata produce un 401 di Genuka, mai un 190.
Fonti
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.
Errore WhatsApp 200: accesso negato (200-299) — soluzione
Errore 200 della WhatsApp Cloud API: token mancante, autorizzazione revocata o un utente di sistema senza accesso all'account. Come diagnosticarlo e risolverlo.