# Errore WhatsApp 190: token di accesso scaduto — causa e soluzione

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

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#authorization-errors)

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](https://developers.facebook.com/docs/graph-api/guides/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/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

1. **Ispeziona il token.** Incollalo nel
   [debugger dei token di accesso di Meta](https://developers.facebook.com/tools/debug/accesstoken/):
   mostra la scadenza e le autorizzazioni. Servono `whatsapp_business_management` e
   `whatsapp_business_messaging`
   ([Meta, WhatsApp support](https://developers.facebook.com/documentation/business-messaging/whatsapp/support#authentication-authorization)).
2. **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](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens#system-user-access-tokens)).
3. **Dagli accesso agli account.** Un utente di sistema senza accesso all'account WhatsApp di
   destinazione non riceve più 190 ma [200](https://wa.genuka.com/it/docs/errors/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).
4. **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ì:

```json title="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](https://wa.genuka.com/it/docs/api#errori)). 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](https://wa.genuka.com/it/docs/onboarding), 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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/authentication).

**Node.js**

```ts
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,
  });
}
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://wa.genuka.com/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}"},
    json={
        "connectionId": "con_1",
        "to": "+237690000001",
        "template": {"name": "order_confirmation", "language": "en_US", "variables": ["Awa", "ORD-1042"]},
    },
    timeout=30,
)
body = response.json()

if response.status_code == 401:
    raise RuntimeError(f"Chiave API rifiutata: {body['error']}")  # la tua chiave Genuka, non Meta
meta = body.get("meta") or {}
if meta.get("code") in (0, 190):
    # Token Meta rifiutato: è dal lato di Genuka. Lancia un avviso, non riprovare.
    print("Token Meta rifiutato", response.headers.get("x-request-id"), meta.get("traceId"))
```

**PHP**

```php
<?php
$ch = curl_init("https://wa.genuka.com/api/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER => true,
    CURLOPT_USERAGENT => "acme-crm/1.0 (+https://example.com)",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("GENUKA_WA_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "connectionId" => "con_1",
        "to" => "+237690000001",
        "template" => ["name" => "order_confirmation", "language" => "en_US", "variables" => ["Awa", "ORD-1042"]],
    ]),
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
curl_close($ch);

$body = json_decode(substr($raw, $headerSize), true);
preg_match('/x-request-id:\s*(\S+)/i', substr($raw, 0, $headerSize), $requestId);

if ($status === 401) {
    throw new RuntimeException("Chiave API rifiutata: " . $body["error"]); // la tua chiave Genuka
}
if (in_array($body["meta"]["code"] ?? null, [0, 190], true)) {
    error_log("Token Meta rifiutato, richiesta " . ($requestId[1] ?? "?") . ", trace " . ($body["meta"]["traceId"] ?? "?"));
}
```

**curl**

```bash
curl -i -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237690000001",
    "template": { "name": "order_confirmation", "language": "en_US", "variables": ["Awa", "ORD-1042"] }
  }'
# -i stampa x-request-id: includilo, insieme a meta.traceId, quando contatti il supporto.
```

## 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/account_update)).
  Genuka WA inoltra questi eventi ai tuoi [webhook](https://wa.genuka.com/it/docs/webhooks) (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](https://wa.genuka.com/it/docs/errors/0): Meta non è riuscita ad autenticare l'utente dell'app; stesso rimedio.
* [200](https://wa.genuka.com/it/docs/errors/200): il token è valido ma non ha accesso all'account o l'autorizzazione.
* [10](https://wa.genuka.com/it/docs/errors/10): autorizzazione non concessa o rimossa.
* [3](https://wa.genuka.com/it/docs/errors/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

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Access tokens](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens)
* [Meta — Graph API, Handling errors](https://developers.facebook.com/docs/graph-api/guides/error-handling)
* [Meta — WhatsApp support, errori di autenticazione e autorizzazione](https://developers.facebook.com/documentation/business-messaging/whatsapp/support#authentication-authorization)
* [Meta — account\_update webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/account_update)
