# Error 190 de WhatsApp: token de acceso vencido — causa y solución

URL: https://wa.genuka.com/es/docs/errors/190
Language: Spanish

> Error 190 de la Cloud API de WhatsApp (token de acceso vencido): qué token venció, cómo reemplazarlo de forma definitiva y por qué los usuarios de Genuka WA nunca manejan tokens de Meta.

El error 190 de WhatsApp significa que el token de acceso enviado a la Cloud API de Meta venció o ya no es
válido. La solución es un token nuevo y, sobre todo, dejar de usar un token de usuario temporal: un token de
usuario del sistema no muere al cabo de unas horas. Con Genuka WA, nunca manejas un token de Meta.

## ¿Qué significa el error 190?

Meta lo clasifica entre los errores de autorización de la Cloud API:

> "Your access token has expired." — solución sugerida: "Get a new access token."
> — [Meta, códigos de error de la Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#authorization-errors)

La documentación general de la Graph API, sobre la que está construida la Cloud API, llama al mismo código "Access
token has expired" y documenta subcódigos
([Meta, Graph API, manejo de errores](https://developers.facebook.com/docs/graph-api/guides/error-handling)):

| Subcódigo de Graph | Nombre que le da Meta | Lo que te indica                                                   |
| ------------------ | --------------------- | ------------------------------------------------------------------ |
| `463`              | Expired               | El token venció, fue revocado o dejó de ser válido por otro motivo |
| `467`              | Invalid Access Token  | El token venció, fue revocado o dejó de ser válido por otro motivo |
| `460`              | Password Changed      | La persona que generó el token cambió su contraseña                |
| `458`              | App Not Installed     | El usuario no inició sesión en tu app                              |

No construyas lógica sobre esos subcódigos: la página de errores de WhatsApp indica que `error_subcode` está obsoleto
y ya no se devuelve a partir de Graph v16.0. El código `190` y el campo `details` bastan.

## ¿Cuándo ocurre el error 190?

* **Estás usando el token de API Setup.** El App Dashboard de Meta genera un token de usuario nuevo cada
  vez que abres **WhatsApp > API Setup**. Meta lo pensó para las primeras pruebas: los tokens de usuario "expire
  quickly" (vencen rápido), así que tienes que generar uno nuevo cada pocas horas
  ([Meta, Access tokens](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens)).
  Es la razón habitual por la que un servicio funciona por la mañana y falla por la tarde.
* **El token fue invalidado.** Contraseña cambiada, app eliminada por el usuario, token revocado: Meta
  responde 190 incluso antes de la fecha de vencimiento.
* **Eres socio y murió el token de un cliente.** Al final del Embedded Signup, un Tech
  Provider recibe un token de usuario del sistema de integración empresarial limitado a ese cliente. Hemos visto
  que deja de funcionar en cuanto el cliente modifica el acceso del socio en su Business Manager:
  Meta responde entonces 190 "Authentication Error" en cada envío, para un número que por lo demás está
  en buen estado.

## ¿Cómo corrijo el error 190?

### Si llamas a la Cloud API con tu propio token

1. **Inspecciona el token.** Pégalo en el
   [depurador de tokens de acceso de Meta](https://developers.facebook.com/tools/debug/accesstoken/): muestra
   el vencimiento y los permisos. Necesita `whatsapp_business_management` y
   `whatsapp_business_messaging`
   ([Meta, WhatsApp support](https://developers.facebook.com/documentation/business-messaging/whatsapp/support#authentication-authorization)).
2. **Reemplaza un token de usuario por un token de usuario del sistema.** En la configuración del negocio, **Usuarios del sistema** (en inglés, *System Users*): crea
   un usuario del sistema, dale el control de tu app y luego **Generate token**, eligiendo la app, una preferencia
   de vencimiento y los permisos `business_management`, `whatsapp_business_management` y
   `whatsapp_business_messaging`
   ([Meta, Access tokens](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens#system-user-access-tokens)).
3. **Dale acceso a las cuentas.** Un usuario del sistema sin acceso a la cuenta de WhatsApp de destino
   ya no recibe 190 sino [200](https://wa.genuka.com/es/docs/errors/200): asígnale la cuenta de WhatsApp y la cuenta de
   mensajería en Meta Business Suite, desde la pestaña **Personas** (en inglés, *People*) de cada cuenta (misma página).
4. **Guárdalo como un secreto opaco.** Meta advierte que el formato de los tokens puede cambiar: sin longitud
   de columna fija, sin decodificarlo.

### Si pasas por Genuka WA

No tienes nada que regenerar. Genuka WA administra el acceso a la Cloud API: cada llamada sobre tu
número sale con el token de usuario del sistema de Genuka, creado sin fecha de vencimiento, y no con el
token que devolvió el Embedded Signup cuando se conectó el número. Genuka tomó esa decisión precisamente para
evitar el caso de socio descrito arriba.

Por lo tanto, un `190` en una respuesta de Genuka WA es, en la gran mayoría de los casos, un incidente del lado de
Genuka. Llega así:

```json title="409 — POST /api/v1/messages"
{
  "error": "send_config",
  "message": "Authentication Error",
  "meta": {
    "errorClass": "config",
    "retryable": false,
    "code": 190,
    "traceId": "AbC…"
  }
}
```

Al crear una plantilla, el mismo rechazo llega como `403 meta_rejected` con el mismo objeto `meta`
([referencia de la API](https://wa.genuka.com/es/docs/api#errores)). En ambos casos:

1. **No reintentes en bucle.** `retryable: false`: la misma llamada fallará de la misma manera.
2. **Contacta al soporte de Genuka** con el encabezado `x-request-id` de la respuesta y `meta.traceId`.
3. **No le pidas al cliente que se vuelva a conectar de inmediato.** Revisa primero `GET /api/v1/connections`.
   `disconnected` significa que Meta reportó que la cuenta ya no se comparte con Genuka, o que fue eliminada, o
   que tú mismo liberaste el número. Un cliente que retiró el acceso lo restablece mediante el
   [enlace de conexión](https://wa.genuka.com/es/docs/onboarding), sin ocupar un espacio nuevo; un número liberado necesita de nuevo un espacio
   libre; una cuenta eliminada, o desactivada por Meta ([error 368](https://wa.genuka.com/es/docs/errors/368)), no
   se restablece así, y el evento `account_update` reenviado a tus webhooks te indica qué
   caso aplica. Si sigue en `connected`, mantente en contacto con el soporte de Genuka.

No lo confundas con los errores de tu propia clave API, que nunca vienen de Meta:
`401 missing_bearer_token` (sin encabezado) y `401 invalid_token` (clave desconocida o revocada), consulta
[Autenticación](https://wa.genuka.com/es/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) {
  // Tu clave de Genuka: ausente, desconocida o revocada. No tiene nada que ver con Meta.
  throw new Error(`Clave API rechazada: ${json.error}`);
}
if (json.meta?.code === 190 || json.meta?.code === 0) {
  // Token de Meta rechazado: del lado de Genuka. Detente y alerta, no reintentes.
  console.error("Token de Meta rechazado", {
    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"Clave API rechazada: {body['error']}")  # tu clave de Genuka, no Meta
meta = body.get("meta") or {}
if meta.get("code") in (0, 190):
    # Token de Meta rechazado: del lado de Genuka. Alerta, no reintentes.
    print("Token de Meta rechazado", 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("Clave API rechazada: " . $body["error"]); // tu clave de Genuka
}
if (in_array($body["meta"]["code"] ?? null, [0, 190], true)) {
    error_log("Token de Meta rechazado, solicitud " . ($requestId[1] ?? "?") . ", traza " . ($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 muestra x-request-id: inclúyelo, junto con meta.traceId, cuando contactes al soporte.
```

## ¿Cómo evito el error 190?

* **Nunca ejecutes producción con el token de API Setup.** Existe para enviar un primer mensaje de prueba, no para
  alimentar un servicio que funciona toda la noche.
* **Un token de usuario del sistema por entorno**, solo con los permisos de WhatsApp que necesitas, guardado en
  tu gestor de secretos.
* **Vigila los accesos revocados.** Como socio, el webhook `account_update` reporta
  `PARTNER_APP_UNINSTALLED` cuando un cliente desautentica o desinstala tu app, y
  `PARTNER_REMOVED` cuando una cuenta deja de compartirse contigo
  ([Meta, account\_update webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/account_update)).
  Genuka WA reenvía estos eventos a tus [webhooks](https://wa.genuka.com/es/docs/webhooks) (evento `account_update`),
  pero de los dos, solo `PARTNER_REMOVED` pasa el número a `disconnected`: después de un
  `PARTNER_APP_UNINSTALLED`, se queda en `connected`.
* **Alerta según la clase, no según el texto.** En Genuka WA, `meta.errorClass: "config"` abarca los problemas de token,
  de permisos y de registro: una persona tiene que revisarlo, y ningún reintento lo arreglará.

## Códigos de error relacionados

* [0](https://wa.genuka.com/es/docs/errors/0): Meta no pudo autenticar al usuario de la app; el mismo remedio.
* [200](https://wa.genuka.com/es/docs/errors/200): el token es válido, pero le falta acceso a la cuenta o un permiso.
* [10](https://wa.genuka.com/es/docs/errors/10): permiso no otorgado o retirado.
* [3](https://wa.genuka.com/es/docs/errors/3): falta una capacidad o un permiso para este endpoint.

## Preguntas frecuentes

### ¿Cuánto dura un token de acceso de la Cloud API de WhatsApp?

Depende del tipo. Un token de usuario, como el de la página API Setup, vence en pocas
horas. Un token de usuario del sistema es de larga duración, y eliges su preferencia de vencimiento cuando lo
generas.

### ¿Debo reintentar un envío que falló con 190?

No hasta que el token haya cambiado. El mismo token produce el mismo error; reintentar solo retrasa la
alerta.

### ¿Mi cliente tiene que volver a conectarse después de un 190 en Genuka WA?

Solo si su número aparece como `disconnected` en `GET /api/v1/connections` porque retiró el acceso de
Genuka: el evento `account_update` reenviado a tus webhooks lo confirma. Una cuenta eliminada,
o desactivada por Meta, no se restablece volviendo a conectarse. Si el número sigue en
`connected`, contacta al soporte de Genuka con `x-request-id` y `meta.traceId`.

### ¿Debo regenerar mi clave API de Genuka?

No. Tu clave `pk_live_…` autentica tus llamadas a Genuka WA, no a Meta. Una clave rechazada produce
un `401` de Genuka, nunca un `190`.

## Fuentes

* [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, authentication and authorization errors](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)
