Error 190 de WhatsApp: token de acceso vencido — causa y solución
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
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):
| 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). 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
Inspecciona el token. Pégalo en el
depurador de tokens de acceso de Meta: muestra
el vencimiento y los permisos. Necesita whatsapp_business_management y
whatsapp_business_messaging
(Meta, WhatsApp support).
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).
Dale acceso a las cuentas. Un usuario del sistema sin acceso a la cuenta de WhatsApp de destino ya no recibe 190 sino 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).
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í:
{
"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). En ambos casos:
- No reintentes en bucle.
retryable: false: la misma llamada fallará de la misma manera. - Contacta al soporte de Genuka con el encabezado
x-request-idde la respuesta ymeta.traceId. - No le pidas al cliente que se vuelva a conectar de inmediato. Revisa primero
GET /api/v1/connections.disconnectedsignifica 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, sin ocupar un espacio nuevo; un número liberado necesita de nuevo un espacio libre; una cuenta eliminada, o desactivada por Meta (error 368), no se restablece así, y el eventoaccount_updatereenviado a tus webhooks te indica qué caso aplica. Si sigue enconnected, 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.
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,
});
}¿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_updatereportaPARTNER_APP_UNINSTALLEDcuando un cliente desautentica o desinstala tu app, yPARTNER_REMOVEDcuando una cuenta deja de compartirse contigo (Meta, account_update webhook). Genuka WA reenvía estos eventos a tus webhooks (eventoaccount_update), pero de los dos, soloPARTNER_REMOVEDpasa el número adisconnected: después de unPARTNER_APP_UNINSTALLED, se queda enconnected. - 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: Meta no pudo autenticar al usuario de la app; el mismo remedio.
- 200: el token es válido, pero le falta acceso a la cuenta o un permiso.
- 10: permiso no otorgado o retirado.
- 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
Error 10 de WhatsApp: permiso denegado — causa y solución
Error 10 de WhatsApp: un permiso que falta, una plantilla OTP en una empresa no verificada, o "Paid Message Account" cuando el número pasó a otra cuenta de WhatsApp Business.
Error 200 de WhatsApp: acceso denegado (200-299) — solución
Error 200 de la Cloud API de WhatsApp: token ausente, permiso revocado o un usuario del sistema sin acceso a la cuenta. Cómo diagnosticarlo y corregirlo.