# Error 3 de WhatsApp: falta una capacidad o un permiso

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

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

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](https://developers.facebook.com/docs/graph-api/guides/error-handling)).

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

| Código                     | Texto de Meta                                           | Lo que falta                                            |
| -------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
| [0](https://wa.genuka.com/es/docs/errors/0)     | "We were unable to authenticate the app user."          | Un usuario autenticable detrás del token                |
| [190](https://wa.genuka.com/es/docs/errors/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](https://wa.genuka.com/es/docs/errors/10)   | "Permission is either not granted or has been removed." | Un permiso, o la elegibilidad para la API que se llama  |
| [200](https://wa.genuka.com/es/docs/errors/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support#authentication-authorization)).
* **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á.

| Canal                    | Lo que recibes                                                                                                                                                                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/v1/messages`  | `409`, `"error": "send_config"`, `meta.code: 3`                                                                                                                                                                                           |
| `POST /api/v1/templates` | `403`, `"error": "meta_rejected"`, `meta.code: 3`                                                                                                                                                                                         |
| Campaña `MARKETING`      | Si 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#marketing-messages-api-for-whatsapp-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

1. **Inspecciona el token** en el
   [depurador de tokens de acceso](https://developers.facebook.com/tools/debug/accesstoken/): ¿a qué app
   pertenece y lleva `whatsapp_business_management` y `whatsapp_business_messaging`?
2. **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](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens#system-user-access-tokens)).
3. **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](https://wa.genuka.com/es/docs/errors/10): permiso no otorgado o retirado, o API no elegible.
* [200](https://wa.genuka.com/es/docs/errors/200): ningún token, o un usuario sin acceso a la cuenta.
* [190](https://wa.genuka.com/es/docs/errors/190): el token venció.
* [0](https://wa.genuka.com/es/docs/errors/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

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Graph API, Handling errors](https://developers.facebook.com/docs/graph-api/guides/error-handling)
* [Meta — WhatsApp support](https://developers.facebook.com/documentation/business-messaging/whatsapp/support)
* [Meta — Access tokens](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens)
