whatsapp.message.updated. Un mensaje puede fallar cuando YCloud valida tu solicitud, cuando envía el mensaje a WhatsApp o después de que WhatsApp acepta el mensaje para su entrega. Usa el código y los detalles devueltos para identificar la causa antes de reintentar.
Encontrar el código de error
El endpoint en cola responde antes de que el mensaje se envíe a WhatsApp, por lo que su respuesta inicial no puede informar de un fallo de envío posterior. El endpoint sincrónico informa del resultado del envío, pero el mensaje aún puede fallar después. Una solicitud aceptada no confirma la entrega; supervisa los webhooks para ambos endpoints.
Leer el código y los detalles
Mantén separados el error de solicitud de YCloud y el error de WhatsApp en origen. Por ejemplo, una respuesta sincrónica puede contenererror.code: "TOO_MANY_REQUESTS" y error.whatsappApiError.code: "131056". El primero describe la respuesta de la API; el segundo identifica el límite de frecuencia entre remitente y destinatario.
Para un webhook de mensaje fallido, whatsappMessage.errorCode puede contener un código de YCloud como BALANCE_INSUFFICIENT o un código de WhatsApp como 131048. Consérvalo como una cadena de texto.
Cuando whatsappApiError esté disponible, inspecciona su code y error_data para conocer la causa específica. Para los errores de la API de mensajes, error_data puede contener una propiedad details; para los errores de la API de plantillas, puede ser en su lugar una cadena de texto. Haz coincidir los códigos en lugar de los títulos de error o el texto del mensaje, que pueden cambiar.
Los códigos numéricos a continuación describen fallos de WhatsApp en origen. Para códigos de YCloud como UNAUTHORIZED, PARAM_INVALID o BALANCE_INSUFFICIENT, consulta Gestionar errores.
Consulta Enviar un mensaje de WhatsApp para conocer los endpoints de envío y Configurar webhooks para recibir actualizaciones del estado de los mensajes.
Límites de envío y restricciones de calidad
Consulta Controles de calidad y entrega para conocer las restricciones de calidad y a nivel de destinatario.
Errores de destinatario y entrega
Errores de mensajes de plantilla y Flow
Comprueba el nombre exacto de la plantilla, el idioma, el estado y las definiciones de los componentes en YCloud antes de volver a intentarlo.
Consulta Administrar plantillas de WhatsApp y Administrar Flows de WhatsApp.
Parámetros del mensaje y archivos multimedia
Consulta Enviar un mensaje de WhatsApp y Subir archivos multimedia de WhatsApp.
Cuenta, número de teléfono y facturación
Errores de mensajes de marketing
Estos errores pueden ocurrir cuando YCloud envía un mensaje a través de la API de mensajes de marketing de Meta. Utiliza los detalles devueltos para distinguir entre problemas de plantilla, sincronización y enrutamiento.
Para esta ruta,
100 puede significar que el mensaje debe ser una plantilla, y 131009 puede indicar parámetros no válidos o una sincronización incompleta de la plantilla. Utiliza los detalles devueltos para distinguir estas causas. En caso de sincronización incompleta, espera 10 minutos antes de volver a intentarlo.
Errores temporales de servicio
Reintentar y escalar
- Corrige los parámetros no válidos, el estado de las plantillas, las restricciones de la cuenta y los problemas con los archivos multimedia antes de volver a intentarlo.
- Respeta las bajas voluntarias y los bloqueos de los destinatarios. No reintentes esos envíos fallidos automáticamente.
- Utiliza retroceso exponencial, variación aleatoria (jitter) y un límite máximo de intentos para errores temporales. Aplica cualquier período de espera especificado anteriormente o en la respuesta.
- Antes de reenviar tras un tiempo de espera agotado o una respuesta ambigua, concilia el estado del mensaje para evitar duplicados.
externalIdes un campo de correlación; no asumas que deduplica los envíos.
requestId de YCloud, el id del mensaje y el wamid o fbtrace_id cuando estén disponibles. Elimina las claves de API y los datos personales innecesarios.