Genuka WA docs

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 GraphNome di MetaCosa ti dice
463ExpiredIl token è scaduto, è stato revocato o non è comunque valido
467Invalid Access TokenIl token è scaduto, è stato revocato o non è comunque valido
460Password ChangedLa persona che ha generato il token ha cambiato la sua password
458App Not InstalledL'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ì:

409 — POST /api/v1/messages
{
  "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:

  1. Non riprovare in un ciclo. retryable: false: la stessa chiamata fallirà allo stesso modo.
  2. Contatta il supporto Genuka con l'header x-request-id della risposta e il meta.traceId.
  3. Non chiedere subito al cliente di ricollegarsi. Controlla prima GET /api/v1/connections. disconnected significa 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'evento account_update inoltrato ai tuoi webhook ti dice di quale caso si tratta. Se risulta ancora connected, 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_update segnala PARTNER_APP_UNINSTALLED quando un cliente revoca l'autenticazione o disinstalla la tua app, e PARTNER_REMOVED quando un account non è più condiviso con te (Meta, account_update webhook). Genuka WA inoltra questi eventi ai tuoi webhook (evento account_update), ma dei due solo PARTNER_REMOVED fa passare il numero a disconnected: dopo un PARTNER_APP_UNINSTALLED, resta connected.
  • 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

In questa pagina