Genuka WA docs

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 GraphNombre que le da MetaLo que te indica
463ExpiredEl token venció, fue revocado o dejó de ser válido por otro motivo
467Invalid Access TokenEl token venció, fue revocado o dejó de ser válido por otro motivo
460Password ChangedLa persona que generó el token cambió su contraseña
458App Not InstalledEl 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í:

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). 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, 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 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.

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_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). Genuka WA reenvía estos eventos a tus 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: 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

En esta página