Solución de problemas

Los síntomas que más vemos durante las integraciones, su causa probable, y qué hacer en cada caso.

Síntoma	Causa probable	Qué hacer
`401` al emitir un token de sesión	Key revocada, expirada o malformada (checksum inválido).	Verifica la key en tu secret store; pídenos una rotación si hay dudas.
`403` — el token no tiene un scope	El token se emitió antes de un cambio de permisos.	Re-emite el token — los scopes viajan dentro de él.
`422` al provisionar un cliente	Un placeholder del blueprint no tiene valor, o las credenciales del connector están vacías.	El campo `detail` nombra la clave exacta que falta. Envíala y reintenta — la llamada es idempotente.
El widget no monta / iframe en blanco	El origen de la página no está en los orígenes permitidos de tu key.	Registra el origen exacto (esquema + host + puerto). Localhost y staging cuentan como orígenes distintos.
Meta rechaza la autorización durante el signup	El código OAuth expiró o se reutilizó.	Cierra el modal y reinicia el flujo — los códigos son de un solo uso y corta vida.
`409` al conectar un número	Ese número de WhatsApp ya está vinculado a otro workspace.	Contáctanos para liberar el número de su workspace anterior primero.
`413` al enviar un broadcast	La audiencia supera tu tope por envío (250 por defecto).	Trocea el envío en lotes, o pídenos subir tu tope.
Una plantilla no aparece en el modal	Aún no está APROBADA en la cuenta de WhatsApp Business de ese cliente.	Espera la aprobación de Meta; el modal solo ofrece plantillas aprobadas.
Error `token_refresh_failed` del SDK	Tu endpoint de sesión falló mientras el modal estaba abierto.	Asegúrate de que el endpoint funciona sin interacción del usuario (se llama ~cada 15 minutos mientras un modal siga abierto).