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

# Gestionar errores de WhatsApp

> Distinga entre errores de solicitud de YCloud, errores de envío de Meta y fallos de entrega asíncronos.

Compruebe tanto la respuesta inicial de la API como los webhooks `whatsapp.message.updated` posteriores. La aceptación por parte de YCloud o Meta no confirma la entrega.

Las siguientes tablas recuperan los casos de error documentados. No constituyen una lista exhaustiva de los errores que Meta puede introducir. Para conocer los detalles actualizados del proveedor, consulte [la referencia de errores de Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes).

## YCloud no pudo enviar mensajes

### `whatsappApiError` en el cuerpo de la respuesta

Es posible que reciba un cuerpo de respuesta de error que incluya el campo `error.whatsappApiError` al enviar mensajes de WhatsApp a través de la API de YCloud, habitualmente con la API Send a WhatsApp message directly (`POST /v2/whatsapp/messages/sendDirectly`).

Aquí tiene un ejemplo de respuesta de error con estado HTTP `429` cuando envía demasiados mensajes al mismo número de teléfono:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 429,
    "code": "TOO_MANY_REQUESTS",
    "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
    "target": "whatsappApiError",
    "docUrl": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes",
    "requestId": "req_1KjtKI80IKoaJNa6n6p",
    "whatsappApiError": {
      "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
      "type": "OAuthException",
      "code": "131056",
      "fbtrace_id": "A4O5a8RAgePwbcGSu",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Message failed to send because there were too many messages sent from this phone number to the same phone number in a short period of time."
      }
    }
  }
}
```

En este caso, intentamos realizar la solicitud a la WhatsApp Business API y obtuvimos una respuesta de error. Se incluye `error.whatsappApiError` para ayudarle a identificar el motivo del error.

### `whatsappApiError` en la carga útil del webhook

Si utiliza la API Enqueue a WhatsApp message (`POST /v2/whatsapp/messages`), nunca recibirá una respuesta de error con `error.whatsappApiError`, ya que enviamos sus mensajes a la WhatsApp Business API de forma asíncrona. Puede obtenerlo configurando un webhook que escuche los eventos `whatsapp.message.updated`. A continuación se muestra un ejemplo de la carga útil del webhook:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "failed",
    "errorCode": "131056",
    "errorMessage": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
    "whatsappApiError": {
      "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
      "type": "OAuthException",
      "code": "131056",
      "fbtrace_id": "A4O5a8RAgePwbcGSu",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Message failed to send because there were too many messages sent from this phone number to the same phone number in a short period of time."
      }
    },
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp"
  }
}
```

### códigos de error devueltos por la WhatsApp Business API

`whatsappApiError` corresponde exactamente al [WhatsApp Business Cloud API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax). A continuación se indican algunos de los posibles códigos de error que pueden devolverse a través de la API de YCloud.

| Código | Descripción | Posibles soluciones | Estado HTTP |
| - | - | - | - |
| `2`<br />API Service | Temporal debido a una caída del servicio o a sobrecarga. | Consulte la página de [estado de WhatsApp Business Platform](https://metastatus.com/whatsapp-business-api) para comprobar el estado de la API antes de volver a intentarlo. | `503`<br />Service Unavailable |
| `100`<br />Invalid parameter | La solicitud incluye uno o más parámetros no admitidos o mal escritos. O el número de teléfono del destinatario no es un número de WhatsApp. | | `400`<br />Bad Request |
| `130429`<br />Rate limit hit | Se ha alcanzado el límite de procesamiento de mensajes de Cloud API. | La aplicación ha alcanzado el límite de procesamiento de la API. Consulte [Throughput](https://developers.facebook.com/docs/whatsapp/cloud-api/overview/#throughput). Vuelva a intentarlo más tarde o reduzca la frecuencia con la que la aplicación envía mensajes. | `429`<br />Too Many Requests |
| `131000`<br />Something went wrong | El mensaje no se pudo enviar debido a un error desconocido. | Vuelva a intentarlo. Si el error persiste, póngase en contacto con nosotros para abrir un ticket en [Direct Support](https://business.facebook.com/direct-support). | `500`<br />Internal Server Error |
| `131008`<br />Required parameter is missing | Falta un parámetro obligatorio en la solicitud. | | `400`<br />Bad Request |
| `131026`<br />Message Undeliverable | No se puede entregar el mensaje. Los motivos pueden incluir: <br /> <br />• El número de teléfono del destinatario no es un número de WhatsApp.<br />• El destinatario no ha aceptado nuestras nuevas Condiciones del servicio y la Política de privacidad. <br />• El destinatario está utilizando un cliente de WhatsApp desactualizado.<br /> | Mediante un método de comunicación distinto de WhatsApp, pida al usuario de WhatsApp que:<br /> • Confirme que realmente puede enviar un mensaje a su número de teléfono comercial de WhatsApp.<br /> • Confirme que ha aceptado nuestras Condiciones del servicio más recientes (en Ajustes > Ayuda o Ajustes > Información de la aplicación se le solicitará que acepte las condiciones/políticas más recientes si aún no lo ha hecho)<br /> • Actualice a la versión más reciente del cliente de WhatsApp. | `400`<br />Bad Request |
| `131031`<br />Account has been locked | La cuenta de WhatsApp Business asociada a la aplicación ha sido restringida o inhabilitada por infringir una política de la plataforma, o no pudimos verificar los datos incluidos en la solicitud con los datos configurados en la cuenta de WhatsApp Business (por ejemplo, el PIN de verificación en dos pasos incluido en la solicitud es incorrecto). | Consulte el documento [Policy Enforcement](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/) para obtener más información sobre las infracciones de políticas y cómo resolverlas. | `403`<br />Forbidden |
| `131056`<br />Se alcanzó el límite de tasa del par (Business Account, Consumer Account) | Se enviaron demasiados mensajes desde el número de teléfono del remitente al mismo número de teléfono del destinatario en un período corto de tiempo. | Espere y vuelva a intentar la operación si tiene la intención de enviar mensajes al mismo número de teléfono. Aún puede enviar mensajes a un número de teléfono diferente sin esperar. | `429`<br />Too Many Requests |
| `132000`<br />No coinciden la cantidad de parámetros de plantilla | La cantidad de valores de parámetros variables incluidos en la solicitud no coincide con la cantidad de parámetros variables definidos en la plantilla. | Asegúrese de que la solicitud incluya todos los valores de parámetros variables que se han definido en la plantilla. | `400`<br />Bad Request |
| `132001`<br />La plantilla no existe | La plantilla no existe en el idioma especificado o no ha sido aprobada. | Asegúrese de que su plantilla haya sido aprobada y que el nombre de la plantilla y la configuración regional del idioma sean correctos. | `400`<br />Bad Request |
| `132007`<br />Violación de la política de caracteres de formato de plantilla | El contenido de la plantilla infringe una política de WhatsApp. | Consulte [Motivos de rechazo](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/#rejection-reasons) para determinar las posibles causas de la infracción. | `400`<br />Bad Request |
| `132012`<br />No coinciden el formato de los parámetros de plantilla | Los valores de los parámetros variables tienen un formato incorrecto. | Los valores de los parámetros variables incluidos en la solicitud no utilizan el formato especificado en la plantilla. | `400`<br />Bad Request |
| `132015`<br />La plantilla está pausada | La plantilla está pausada debido a su baja calidad, por lo que no se puede enviar en un mensaje de plantilla. | Edite la plantilla para mejorar su calidad y vuelva a intentarlo una vez que sea aprobada. | `400`<br />Bad Request |
| `132016`<br />La plantilla está deshabilitada | La plantilla se ha pausado demasiadas veces debido a su baja calidad y ahora está deshabilitada de forma permanente. | Cree una nueva plantilla con un contenido diferente. | `400`<br />Bad Request |
| `133010`<br />Número de teléfono no registrado | El número de teléfono comercial no está registrado en WhatsApp Business Platform. | Registre el número de teléfono antes de volver a intentarlo. | `400`<br />Bad Request |
| `130472`<br />El número de usuario forma parte de un experimento | El mensaje no se envió como parte de un [experimento](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments). | Consulte el [Experimento de mensajes de marketing](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments#marketing-message-experiment). | `400`<br />Bad Request |

### códigos de error devueltos por la API de YCloud

Tenga en cuenta que `error.whatsappApiError` no se incluye cuando YCloud detecta los errores y no solicitamos la WhatsApp Business API. Por ejemplo, si proporciona un número de teléfono no válido, obtendrá la siguiente respuesta de error:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 400,
    "code": "PARAM_INVALID",
    "message": "Invalid E.164 phone number: +001",
    "target": "to",
    "docUrl": "https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/handle-errors#error-codes",
    "requestId": "req_69UpMOaMHFrBMGZexYvUDw"
  }
}
```

El valor `error.code` es uno de los [códigos de error](/es/api-reference/guides/api-fundamentals/handle-errors#error-codes) definidos por el servidor de YCloud.

A continuación se indican algunos de los posibles códigos de error devueltos por la API de YCloud:

| Código | Descripción | Estado HTTP |
| :- | :- | :- |
| PARAM\_INVALID | Uno o más de los parámetros no son válidos. | `400`<br />Bad Request |
| PARAM\_MISSING | Faltan uno o más de los parámetros. | `400`<br />Bad Request |
| BALANCE\_INSUFFICIENT | El saldo de la cuenta es insuficiente. | `403`<br />Forbidden |
| WHATSAPP\_WABA\_UNAVAILABLE | La cuenta de WhatsApp Business no está disponible. | `403`<br />Forbidden |
| WHATSAPP\_PHONE\_NUMBER\_UNAVAILABLE | El número de teléfono comercial de WhatsApp no está disponible. | `403`<br />Forbidden |
| WHATSAPP\_TEMPLATE\_UNAVAILABLE | La plantilla de WhatsApp no está disponible. | `403`Forbidden |
| UNAUTHORIZED | No autorizado. Asegúrate de estar usando la API Key correcta en el encabezado 'X-API-Key'. | `401`<br />Unauthorized |

### Códigos de error de YCloud transmitidos por webhooks

Si utilizas el endpoint Enqueue a WhatsApp message (`POST /v2/whatsapp/messages`), el mensaje puede fallar debido a un error de YCloud. Es decir, el `whatsappMessage.errorCode` en la carga útil del webhook también puede transmitir uno de los [Códigos de error de YCloud](/es/api-reference/guides/api-fundamentals/handle-errors#error-codes), como `BALANCE_INSUFFICIENT`.

Estos son algunos posibles errores:

| Código de error | Descripción | Posibles soluciones |
| :- | :- | :- |
| `INTERNAL_SERVER_ERROR` | Temporal debido a tiempo de inactividad o sobrecarga. | Espera y reintenta la operación.<br />Este error puede deberse a un tiempo de espera agotado en nuestra llamada a la WhatsApp Business API. |
| `BALANCE_INSUFFICIENT` | El saldo de tu cuenta es insuficiente. | Recarga saldo. |
| `RECIPIENT_UNSUBSCRIBED` | El destinatario ha cancelado la suscripción. | Respeta la exclusión voluntaria del usuario. Reanuda el envío de mensajes solo después de que el usuario haya vuelto a dar su consentimiento válido y tus registros de suscripción se hayan actualizado. |

## Meta no pudo enviar los mensajes

No todos los códigos de error listados en la página [WhatsApp Business Cloud API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax) se devuelven a través de la API de YCloud. Incluso si un mensaje se envía correctamente a la WhatsApp Business API, también puede fallar en su entrega. Meta notifica a YCloud sobre estos errores a través de webhooks. Debes [Configurar Webhooks](/es/api-reference/guides/api-fundamentals/configure-webhooks) que escuchen eventos `whatsapp.message.updated` para recibir estas notificaciones de YCloud. Aquí tienes un ejemplo de la carga útil del webhook para mensajes enviados que finalmente fallaron:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "failed",
    "errorCode": "131048",
    "errorMessage": "Message failed to send because there are restrictions on how many messages can be sent from this phone number.This may be because too many previous messages were blocked or flagged as spam.",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp"
  }
}
```

El `whatsappMessage.errorCode` transmite el código de [Error de WhatsApp Business API](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax).

### Códigos de error de Meta transmitidos por webhooks

A continuación se enumeran algunos posibles códigos de error transmitidos por los webhooks de YCloud originados en los webhooks de Meta:

| Código | Descripción | Posibles soluciones |
| - | - | - |
| `131000`<br />Something went wrong | El mensaje no se pudo enviar debido a un error desconocido. | Inténtalo de nuevo. Si el error persiste, contáctanos para abrir un ticket de [Direct Support](https://business.facebook.com/direct-support). |
| `131026`<br />Message Undeliverable | No se pudo entregar el mensaje. Los motivos pueden incluir: <br /> <br />• El número de teléfono del destinatario no es un número de WhatsApp.<br />• El destinatario no ha aceptado nuestras nuevas Condiciones del servicio y Política de privacidad. <br />• El destinatario utiliza un cliente de WhatsApp desactualizado.<br /> | Mediante un método de comunicación que no sea WhatsApp, pide al usuario de WhatsApp que:<br /> • Confirme que realmente puede enviar un mensaje a tu número de teléfono comercial de WhatsApp.<br /> • Confirme que ha aceptado nuestras Condiciones del servicio más recientes (Ajustes > Ayuda o Ajustes > Información de la aplicación le solicitarán que acepte los términos/políticas más recientes si aún no lo ha hecho)<br /> • Actualice a la versión más reciente del cliente de WhatsApp. |
| `131031`<br />Account has been locked | La cuenta de WhatsApp Business asociada a la aplicación se ha restringido o inhabilitado por infringir una política de la plataforma, o no pudimos verificar los datos incluidos en la solicitud con los datos configurados en la cuenta de WhatsApp Business (por ejemplo, el PIN de verificación en dos pasos incluido en la solicitud es incorrecto). | Consulta el documento [Policy Enforcement](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/) para obtener más información sobre las infracciones de políticas y cómo resolverlas. |
| `131047`<br />Re-engagement message | Han pasado más de 24 horas desde que el destinatario respondió por última vez al número del remitente. | En su lugar, envía al destinatario un mensaje iniciado por la empresa utilizando una plantilla de mensaje. |
| `131048`<br />Se alcanzó el límite de tasa de spam | No se pudo enviar el mensaje porque existen restricciones sobre cuántos mensajes se pueden enviar desde este número de teléfono. Esto puede deberse a que se bloquearon o marcaron como spam demasiados mensajes anteriores. | Consulta tu estado de calidad en el Administrador de WhatsApp y revisa la documentación de [Límites de velocidad basados en la calidad](https://developers.facebook.com/docs/whatsapp/messaging-limits#quality-rating-and-messaging-limits) para obtener más información. |
| `131049`<br /> | Este mensaje no se entregó para mantener una interacción saludable en el ecosistema. | No vuelvas a intentarlo de inmediato si recibes este código de error y sospechas que se debe al límite. En su lugar, vuelve a intentarlo con intervalos de tiempo cada vez mayores hasta que se entregue el mensaje, ya que el límite puede estar vigente durante diferentes periodos de tiempo.<br />Consulta [Límites de mensajes de plantillas de marketing por usuario](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits) para obtener información adicional. |
| `131053`<br />Error al subir archivo multimedia | No se pudo subir el archivo multimedia utilizado en el mensaje. | No pudimos subir el archivo multimedia por uno o más motivos, como un [tipo de contenido multimedia no admitido](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). |
| `131050`<br />Mensaje no entregable | No se pudo entregar el mensaje. Este destinatario ha decidido dejar de recibir mensajes de marketing en WhatsApp de tu empresa | |


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