Genuka WA docs

Error 3 de WhatsApp: falta una capacidad o un permiso

Error 3 de la Cloud API de WhatsApp (Capability or permissions issue): en qué se diferencia de los errores 0, 10, 190 y 200, y cómo corregirlo.

El error 3 de WhatsApp significa que a la aplicación que llama a la Cloud API le falta la capacidad o el permiso que exige este endpoint en particular. El token puede ser perfectamente válido: es la app la que no tiene autorización para hacer esa llamada concreta. Se corrige otorgando el permiso o la función que falta, nunca enviando de nuevo la misma solicitud.

¿Qué significa el error 3?

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

"Capability or permissions issue." — Meta, códigos de error de la Cloud API

La solución sugerida: verificar en el depurador de tokens de acceso que la app recibió los permisos que exige el endpoint. La documentación general de Graph llama a este código "API Method" y lo resume así: "Make sure your app has the necessary capability or permissions to make this call" (asegúrate de que tu app tenga la capacidad o los permisos necesarios para hacer esta llamada) (Meta, Graph API, manejo de errores).

¿Cómo lo distingues de los demás errores de autorización?

Cada uno de los seis códigos de autorización de la Cloud API responde a una pregunta diferente. Los textos provienen de la página de errores de Meta:

CódigoTexto de MetaLo que falta
0"We were unable to authenticate the app user."Un usuario autenticable detrás del token
190"Your access token has expired."Un token que siga siendo válido
3"Capability or permissions issue."Una capacidad o un permiso de la app para este endpoint
10"Permission is either not granted or has been removed."Un permiso, o la elegibilidad para la API que se llama
200"No access token was provided."Un token en la solicitud
200 a 299"Permission is either not granted or has been removed."Un permiso, o el acceso del usuario a la cuenta

Ten presente la frontera: con 0 y 190, el token en sí está muerto; con 200 ("No access token was provided") no hay ningún token; con 3, 10 y 201 a 299, el token está vivo, pero no da acceso a lo que pides.

¿Cuándo ocurre el error 3?

  • El token se generó sin los permisos de WhatsApp, o para una app distinta de la que hace la llamada. Al generarlo, Meta te pide seleccionar la app usada para las llamadas y los permisos whatsapp_business_management y whatsapp_business_messaging (Meta, WhatsApp support).
  • El endpoint pertenece a una función que la app o la cuenta no ha habilitado. La Marketing Messages API es un ejemplo: exige una incorporación completada por un usuario del portafolio con control total (misma página). Mientras esa incorporación no esté hecha, la llamada no tiene por qué funcionar.

¿Dónde lo ves en Genuka WA?

Genuka WA coloca el código 3 en la clase config: un problema de token, de permiso o de registro que un reintento no corregirá.

CanalLo que recibes
POST /api/v1/messages409, "error": "send_config", meta.code: 3
POST /api/v1/templates403, "error": "meta_rejected", meta.code: 3
Campaña MARKETINGSi la Marketing Messages API rechaza el envío con un error 4xx de permiso o de parámetro (códigos 3, 10, 100…), Genuka reenvía el mensaje por el endpoint normal /messages; si este también lo rechaza, el destinatario pasa a failed

El último caso es intencional. Meta no expone ningún indicador que diga de antemano si una cuenta tiene acceso a la Marketing Messages API: Genuka lo intenta, trata un rechazo 4xx de tipo permiso como "función no disponible en esta cuenta" y reenvía el mensaje por la vía normal. Esta alternativa es silenciosa: solo se registra el resultado del envío por /messages. No cubre todos los rechazos: Meta también reporta la falta de elegibilidad con el código 134102 y un estado HTTP 500 (Meta, Marketing Messages API error codes); Genuka lo trata como una caída transitoria, lo reintenta y luego marca al destinatario como failed.

¿Cómo corrijo el error 3?

Si llamas a la Cloud API con tu propio token

Inspecciona el token en el depurador de tokens de acceso: ¿a qué app pertenece y lleva whatsapp_business_management y whatsapp_business_messaging?

Regenéralo si hace falta, seleccionando la app correcta y ambos permisos de WhatsApp. Para un servicio en producción, prefiere un token de usuario del sistema (Meta, Access tokens).

Revisa los requisitos de la función que llamas. Si el endpoint pertenece a una función que exige incorporación o elegibilidad, como la Marketing Messages API, complétala primero antes de volver a intentarlo.

Si pasas por Genuka WA

No tienes ningún token de Meta que corregir: un código 3 en un envío o en la creación de una plantilla le corresponde a Genuka. Contacta al soporte con el encabezado x-request-id de la respuesta y meta.traceId. Si envías un tipo de mensaje avanzado mediante el campo raw, indícalo: es ahí donde es más probable que aparezca una función que no está habilitada.

¿Cómo evito el error 3?

  • Genera cada token para la app correcta, solo con los permisos de WhatsApp que necesitas.
  • Antes de adoptar una nueva función de Meta, lee sus requisitos de acceso: muchas necesitan su propia incorporación o elegibilidad.
  • Alerta según la clase config, no según el texto del mensaje: Meta advierte que los títulos de error terminarán quedando obsoletos.

Códigos de error relacionados

  • 10: permiso no otorgado o retirado, o API no elegible.
  • 200: ningún token, o un usuario sin acceso a la cuenta.
  • 190: el token venció.
  • 0: Meta no pudo autenticar al usuario de la app.

Preguntas frecuentes

¿Cuál es la diferencia entre el error 3 y el error 10?

Meta asocia el 3 a una capacidad o un permiso que falta para el endpoint, y el 10 a un permiso no otorgado o retirado, incluso cuando la cuenta no es elegible para la API que se llama. En ambos casos el token está vivo; lo que autoriza no basta.

¿Debo reintentar una llamada rechazada con el error 3?

No. Mientras falte el permiso o la función, la misma solicitud fallará de la misma manera.

¿Puede fallar con el error 3 un destinatario de una campaña de marketing?

Sí. Un rechazo de la Marketing Messages API por sí solo nunca te llega: Genuka reenvía el mensaje por /messages, y ese segundo envío es el que cuenta. Si el destinatario aun así pasa a failed con un motivo de permiso, /messages también lo rechazó: el problema afecta al número, no solo a la Marketing Messages API, y le corresponde al soporte de Genuka.

Fuentes

En esta página