> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Código de error de WhatsApp

> Consulta los códigos de error de mensajería de WhatsApp y resuelve los mensajes fallidos enviados a través de YCloud.

Supervisa tanto la respuesta de la API como los webhooks de `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

| Dónde ocurre el fallo | Dónde leer el error |
| - | - |
| YCloud rechaza la solicitud antes de enviarla a WhatsApp | Lee `error.code`, `error.message` y `error.target` en la respuesta de la API. No hay ningún `whatsappApiError` de origen disponible. |
| WhatsApp rechaza un envío sincrónico a través de `POST /v2/whatsapp/messages/sendDirectly` | Lee los campos de error de YCloud junto con `error.whatsappApiError`, cuando esté presente. Su `code` identifica el error de WhatsApp en origen. |
| Un mensaje en cola falla durante el envío a través de `POST /v2/whatsapp/messages` | Lee `whatsappMessage.status`, `whatsappMessage.errorCode` y `whatsappMessage.errorMessage` en el webhook `whatsapp.message.updated`. Inspecciona `whatsappMessage.whatsappApiError` cuando esté presente. |
| WhatsApp acepta el mensaje pero luego no puede entregarlo | Lee `whatsappMessage.errorCode` y `whatsappMessage.errorMessage` en un webhook `whatsapp.message.updated` con `whatsappMessage.status: "failed"`. No requieras un objeto `whatsappApiError` para procesar el fallo. |
| Un mensaje entrante contiene un error de contenido no admitido o de multimedia | En el webhook `whatsapp.inbound_message.received`, inspecciona `whatsappInboundMessage.errors[]` cuando esté presente. Cada entrada puede incluir `code`, `message` y `error_data.details`. |

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 contener `error.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](/es/api-reference/guides/api-fundamentals/handle-errors).

Consulta [Enviar un mensaje de WhatsApp](/es/api-reference/guides/whatsapp-platform/send-whatsapp-message) para conocer los endpoints de envío y [Configurar webhooks](/es/api-reference/guides/api-fundamentals/configure-webhooks) para recibir actualizaciones del estado de los mensajes.

## Límites de envío y restricciones de calidad

| Código | Significado | Qué hacer |
| - | - | - |
| `80007` | La cuenta de WhatsApp Business ha alcanzado su límite de llamadas a la API. | Reduce las solicitudes para la WABA afectada y vuelve a intentarlo más tarde con un intervalo exponencial. |
| `130429` | Se ha superado el rendimiento de mensajes. | Reduce la velocidad de envío para el número de teléfono comercial afectado y distribuye los envíos a lo largo del tiempo. |
| `131048` | El envío está restringido debido a señales de spam o calidad. | Pausa los envíos afectados. Revisa la calidad del número de teléfono, el consentimiento de la audiencia y los comentarios negativos recientes antes de reanudar. |
| `131056` | Se enviaron demasiados mensajes desde un número comercial al mismo destinatario en un período corto. | Espera antes de volver a intentar con ese par remitente-destinatario. Este límite específico no impide envíos a otros destinatarios. |
| `131064` | Las infracciones en la clasificación de plantillas han provocado una restricción de mensajería. | Revisa las categorías de plantilla y corrige el contenido mal clasificado. La restricción se aplica a los mensajes de plantilla y de Direct Send, y se levanta después del período de aplicación. |

Consulta [Controles de calidad y entrega](/es/documentation/whatsapp-business-platform/pricing-limits-and-quality/quality-and-delivery-controls) para conocer las restricciones de calidad y a nivel de destinatario.

## Errores de destinatario y entrega

| Código | Significado | Qué hacer |
| - | - | - |
| `130403` | Tu empresa ha bloqueado al destinatario en WhatsApp. | No reintentes mientras permanezca el bloqueo. Revisa el bloqueo antes de decidir si se debe reanudar la comunicación. |
| `130472` | WhatsApp retuvo el mensaje como parte de un experimento de la plataforma. | No reenvíes repetidamente el mismo mensaje. Usa otro canal de comunicación acordado si la información es urgente. |
| `131021` | El número de teléfono del remitente y del destinatario son el mismo. | Envía a un número de destinatario diferente. |
| `131026` | No se pudo entregar el mensaje. Las causas posibles incluyen un número que no está en WhatsApp, condiciones de WhatsApp no aceptadas o un cliente desactualizado. | A través de otro canal acordado, pídele al destinatario que confirme que puede enviar mensajes a tu empresa, acepte las condiciones actuales de WhatsApp y actualice WhatsApp. El código por sí solo no identifica una causa definitiva. |
| `131047` | La ventana de servicio de atención al cliente de 24 horas ha expirado. | Envía una plantilla aprobada adecuada o espera un nuevo mensaje del cliente antes de enviar una respuesta de formato libre. |
| `131049` | WhatsApp retuvo el mensaje para proteger la interacción del destinatario. | Evita reintentos inmediatos. Si sospechas de un límite de marketing del destinatario, espera al menos 24 horas antes de considerar otro envío. Primero comprueba el consentimiento y la relevancia; esperar no garantiza la entrega. |
| `131050` | El destinatario detuvo los mensajes de marketing de tu empresa en WhatsApp. | Detén los envíos de marketing a este destinatario. No reintentes enviar el mensaje de marketing fallido. |

## 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.

| Código | Significado | Qué hacer |
| - | - | - |
| `132000` | La cantidad de parámetros de plantilla proporcionados no coincide con la plantilla. | Proporciona la cantidad requerida de valores para cada componente. |
| `132001` | La plantilla no existe en el idioma solicitado o no está aprobada. | Comprueba el nombre, el código de idioma, la WABA y el estado de aprobación. |
| `132005` | El texto de la plantilla supera la longitud permitida. | Revisa la plantilla y los valores de texto proporcionados según los límites de longitud aplicables. |
| `132007` | El contenido de la plantilla infringe una política de WhatsApp. | Revisa la infracción notificada y corrige el contenido antes de volver a enviarla. |
| `132012` | Los formatos de los parámetros de la plantilla no coinciden con la definición. | Comprueba cada componente y tipo de parámetro, incluidos los encabezados multimedia y los botones. |
| `132015` | La plantilla está en pausa debido a baja calidad. | Detén los envíos que la utilicen. Mejora su contenido y reanúdalos solo cuando la plantilla esté aprobada y se pueda usar. |
| `132016` | La plantilla está inhabilitada permanentemente tras repetidas pausas por calidad. | Crea un reemplazo con contenido diferente y soluciona el problema de calidad antes de enviar. |
| `132068` | El Flow utilizado en el mensaje está bloqueado. | Comprueba el estado del Flow y resuelve el problema notificado antes de usarlo de nuevo. |
| `132069` | El Flow tiene una limitación de frecuencia (throttled) y ha alcanzado su límite de envío. | Revisa el estado del Flow y los envíos recientes. Resuelve el problema y espera antes de volver a intentarlo. |

Consulta [Administrar plantillas de WhatsApp](/es/api-reference/guides/whatsapp-platform/manage-whatsapp-templates) y [Administrar Flows de WhatsApp](/es/api-reference/guides/whatsapp-platform/manage-whatsapp-flows).

## Parámetros del mensaje y archivos multimedia

| Código | Significado | Qué hacer |
| - | - | - |
| `100` | La solicitud contiene un parámetro no admitido o no válido. | Lee los detalles devueltos y corrige el campo correspondiente utilizando la referencia del endpoint de YCloud. |
| `131008` | Falta un parámetro obligatorio. | Agrega el campo o componente identificado en el error. |
| `131009` | El valor de un parámetro no es válido. | Corrige el valor, formato o longitud identificados en los detalles del error. |
| `131051` | El tipo de mensaje no es compatible. | Para envíos salientes, usa un tipo de mensaje admitido por YCloud. Para mensajes entrantes, gestiona el evento no admitido sin asumir que el contenido del mensaje habitual esté disponible. |
| `131052` | WhatsApp no pudo descargar el contenido multimedia enviado por el usuario. | Inspecciona los detalles del error entrante. Pídele al usuario que comparta el archivo a través de otro canal acordado si es necesario. |
| `131053` | No se pudo subir el archivo multimedia utilizado en el mensaje de salida. | Comprueba el formato real del archivo, el tipo MIME, el tamaño y la accesibilidad. Corrige el archivo o la URL antes de volver a intentarlo. |
| `135000` | WhatsApp reportó un error de parámetro de solicitud no especificado. | Comprueba la solicitud con el esquema de la API de YCloud y conserva los detalles devueltos. |

Consulta [Enviar un mensaje de WhatsApp](/es/api-reference/guides/whatsapp-platform/send-whatsapp-message) y [Subir archivos multimedia de WhatsApp](/es/api-reference/guides/whatsapp-platform/upload-whatsapp-media).

## Cuenta, número de teléfono y facturación

| Código | Significado | Qué hacer |
| - | - | - |
| `368`, `131031` | La WABA está restringida o bloqueada. En el caso de `131031`, también pueden intervenir los datos de verificación de la cuenta. | Comprueba el estado de la cuenta y los detalles exactos del error. |
| `130497` | La WABA no puede enviar mensajes a usuarios de ciertos países. | Comprueba el destino y las restricciones de tu categoría comercial. No reintentes enviar a un destino no admitido sin realizar cambios. |
| `131042` | WhatsApp reportó un problema de pago o facturación de la cuenta. | Comprueba la conexión de facturación de la WABA. Esto es independiente de `BALANCE_INSUFFICIENT` de YCloud; recargar saldo por sí solo tal vez no lo resuelva. |
| `131045`, `133010` | El número de teléfono comercial tiene un problema de registro o no está registrado. | Comprueba el estado de conexión y registro del número en YCloud. |
| `131057` | La cuenta se encuentra temporalmente en modo de mantenimiento. | Espera a que termine el mantenimiento y vuelve a intentarlo con retroceso gradual. |

## 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.

| Código | Significado | Qué hacer |
| - | - | - |
| `131055`, `134100` | La ruta ascendente de marketing solo acepta plantillas de marketing. | Confirma que el mensaje deseado utilice una plantilla de `MARKETING`. Las plantillas de utilidad y de autenticación requieren una ruta de envío diferente. |
| `131063` | Las plantillas de marketing están deshabilitadas en la ruta de la Cloud API de la cuenta. | Comprueba la ruta de envío de marketing y la configuración de la cuenta. |
| `134101` | La plantilla de marketing aún se está sincronizando. | Espera 10 minutos antes de volver a intentar con la plantilla recién creada. |
| `134102` | La plantilla no está disponible porque la sincronización o la elegibilidad de la cuenta no están completas. | Comprueba la elegibilidad de la cuenta y si la sincronización de la plantilla ha finalizado. |
| `132018` | Error en la validación de los parámetros de la plantilla. | Corrige los parámetros identificados en el error y vuelve a enviar solo después de que la validación sea correcta. |

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

| Código | Significado | Qué hacer |
| - | - | - |
| `1` | Solicitud no válida o error del servidor ascendente. | Comprueba la solicitud primero. Si es válida, investiga si se trata de un problema temporal del servicio. |
| `2`, `131016` | Un servicio ascendente no está disponible temporalmente o está sobrecargado. | Comprueba el [estado de WhatsApp Business Platform](https://metastatus.com/whatsapp-business-api) y reintenta los fallos temporales con un retroceso delimitado. |
| `131000` | Un fallo no especificado de WhatsApp. | Comprueba el estado del servicio y los detalles devueltos. Utiliza reintentos delimitados solo cuando sea adecuado. |

## 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. `externalId` es un campo de correlación; no asumas que deduplica los envíos.

Si un error persiste tras las comprobaciones anteriores, o si necesitas ayuda con la facturación de la cuenta, la elegibilidad o la configuración de la ruta de envío, ponte en contacto con el [soporte de YCloud](https://www.ycloud.com/console/#/app/getStarted). Incluye la hora del fallo y la zona horaria, el endpoint, el código y los detalles exactos del error, el `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.