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

# Handle WhatsApp errors

> Distinguish YCloud request errors, Meta submission errors, and asynchronous delivery failures.

Check both the initial API response and later `whatsapp.message.updated`
webhooks. Acceptance by YCloud or Meta does not confirm delivery.

The tables below restore the documented error cases. They are not an exhaustive
list of errors Meta can introduce. For current provider details, use
[Meta's error reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes).

## YCloud failed to send messages

### `whatsappApiError` in response body

You may get an error response body including the field `error.whatsappApiError` when you send WhatsApp messages by the YCloud API, typically the Send a WhatsApp message directly (`POST /v2/whatsapp/messages/sendDirectly`) API.

Here is a sample error response with HTTP status `429`  when you send too many messages to the same phone number:

```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."
      }
    }
  }
}
```

In this case, we tried to request the WhatsApp Business API and got an error response. `error.whatsappApiError` is included to help you identify the error reason.

### `whatsappApiError` in webhook payload

If you are using the Enqueue a WhatsApp message (`POST /v2/whatsapp/messages`) API, you will never get an error response having `error.whatsappApiError` since we submit your messages to the WhatsApp Business API asynchronously. You can get it by configuring a webhook listening for `whatsapp.message.updated` events. Here is an example of the webhook payload:

```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"
  }
}
```

### error codes returned by the WhatsApp Business API

The `whatsappApiError` is exactly the [WhatsApp Business Cloud API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax). Listed below are some possible error codes that may be returned through the YCloud API.

| Code | Description | Possible Solutions | HTTP Status |
| - | - | - | - |
| `2`<br />API Service | Temporary due to downtime or due to being overloaded. | Check the [WhatsApp Business Platform Status](https://metastatus.com/whatsapp-business-api) page to see API status information before trying again. | `503`<br />Service Unavailable |
| `100`<br />Invalid parameter | The request included one or more unsupported or misspelled parameters. Or the recipient phone number is not a WhatsApp phone number. | | `400`<br />Bad Request |
| `130429`<br />Rate limit hit | Cloud API message throughput has been reached. | The app has reached the API's throughput limit. See [Throughput](https://developers.facebook.com/docs/whatsapp/cloud-api/overview/#throughput). Try again later or reduce the frequency with which the app sends messages. | `429`<br />Too Many Requests |
| `131000`<br />Something went wrong | Message failed to send due to an unknown error. | Try again. If the error persists, contact us to open a [Direct Support](https://business.facebook.com/direct-support) ticket. | `500`<br />Internal Server Error |
| `131008`<br />Required parameter is missing | The request is missing a required parameter. | | `400`<br />Bad Request |
| `131026`<br />Message Undeliverable | Unable to deliver message. Reasons can include: <br /> <br />• The recipient phone number is not a WhatsApp phone number.<br />• Recipient has not accepted our new Terms of Service and Privacy Policy. <br />• Recipient using an outdated WhatsApp client.<br /> | Using a non-WhatsApp communication method, ask the WhatsApp user to:<br /> • Confirm that they can actually send a message to your WhatsApp business phone number.<br /> • Confirm that they have accepted our latest Terms of Service (Settings > Help, or Settings > Application information will prompt them to accept the latest terms/policies if they haven't done so already)<br /> • Update to the latest version of the WhatsApp client. | `400`<br />Bad Request |
| `131031`<br />Account has been locked | The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy, or we were unable to verify data included in the request against data set on the WhatsApp Business Account (e.g, the two-step pin included in the request is incorrect). | See the [Policy Enforcement](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/) document to learn about policy violations and how to resolve them. | `403`<br />Forbidden |
| `131056`<br />(Business Account, Consumer Account) pair rate limit hit | Too many messages sent from the sender phone number to the same recipient phone number in a short period of time. | Wait and retry the operation, if you intend to send messages to the same phone number. You can still send messages to a different phone number without waiting. | `429`<br />Too Many Requests |
| `132000`<br />Template Param Count Mismatch | The number of variable parameter values included in the request did not match the number of variable parameters defined in the template. | Make sure the request includes all of the variable parameter values that have been defined in the template. | `400`<br />Bad Request |
| `132001`<br />Template does not exist | The template does not exist in the specified language or the template has not been approved. | Make sure your template has been approved and the template name and language locale are correct. | `400`<br />Bad Request |
| `132007`<br />Template Format Character Policy Violated | Template content violates a WhatsApp policy. | See [Rejection Reasons](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/#rejection-reasons) to determine possible reasons for violation. | `400`<br />Bad Request |
| `132012`<br />Template Parameter Format Mismatch | Variable parameter values formatted incorrectly. | The variable parameter values included in the request are not using the format specified in the template. | `400`<br />Bad Request |
| `132015`<br />Template is Paused | Template is paused due to low quality so it cannot be sent in a template message. | Edit the template to improve its quality and try again once it is approved. | `400`<br />Bad Request |
| `132016`<br />Template is Disabled | Template has been paused too many times due to low quality and is now permanently disabled. | Create a new template with different content. | `400`<br />Bad Request |
| `133010`<br />Phone number Not Registered | Business Phone number not registered on the WhatsApp Business Platform. | Register the phone number before trying again. | `400`<br />Bad Request |
| `130472`<br />User's number is part of an experiment | Message was not sent as part of an [experiment](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments). | See [Marketing Message Experiment](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments#marketing-message-experiment). | `400`<br />Bad Request |

### error codes returned by the YCloud API

Be aware that `error.whatsappApiError` is not included when errors were detected by YCloud and we didn't request the WhatsApp Business API. For example, you provide an invalid phone number and then get the error response:

```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"
  }
}
```

The `error.code` is one of the YCloud server-defined [error codes](/en/api-reference/guides/api-fundamentals/handle-errors#error-codes).

Listed below are some possible error codes returned by the YCloud API:

| Code | Description | HTTP Status |
| :- | :- | :- |
| PARAM\_INVALID | One or more of the parameters is invalid. | `400`<br />Bad Request |
| PARAM\_MISSING | One or more of the parameters is missing. | `400`<br />Bad Request |
| BALANCE\_INSUFFICIENT | The account balance is insufficient. | `403`<br />Forbidden |
| WHATSAPP\_WABA\_UNAVAILABLE | The WhatsApp business account is unavailable. | `403`<br />Forbidden |
| WHATSAPP\_PHONE\_NUMBER\_UNAVAILABLE | The WhatsApp business phone number is unavailable. | `403`<br />Forbidden |
| WHATSAPP\_TEMPLATE\_UNAVAILABLE | The WhatsApp template is unavailable. | `403`Forbidden |
| UNAUTHORIZED | Unauthorized. Make sure you are using the correct API Key in the 'X-API-Key' header. | `401`<br />Unauthorized |

### YCloud error codes conveyed by webhooks

If you are using the Enqueue a WhatsApp message (`POST /v2/whatsapp/messages`) endpoint, the message may fail due to a YCloud error. That is, the `whatsappMessage.errorCode` in webhook payload can also convey one of the [YCloud Error Codes](/en/api-reference/guides/api-fundamentals/handle-errors#error-codes), such as `BALANCE_INSUFFICIENT`.

Here are some possible errors:

| Error Code | Description | Possible Solutions |
| :- | :- | :- |
| `INTERNAL_SERVER_ERROR` | Temporary due to downtime or due to being overloaded. | Wait and retry the operation.<br />This error may be caused by a timeout in our call to the WhatsApp Business API. |
| `BALANCE_INSUFFICIENT` | Your account balance is insufficient. | Top-up. |
| `RECIPIENT_UNSUBSCRIBED` | The recipient has unsubscribed. | Respect the user's opt-out. Resume messaging only after the user has provided valid consent again and your subscription records have been updated. |

## Meta failed to send messages

Not all of the error codes listed in the [WhatsApp Business Cloud API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax) page are returned through the YCloud API. Even if a message is successfully submitted to the WhatsApp Business API, it may also fail to send. Meta notifies YCloud about these errors via webhooks. You should [Configure Webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks) listening for `whatsapp.message.updated` events to receive these notifications from YCloud. Here is an example of the webhook payload for submitted but finally failed messages:

```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"
  }
}
```

The `whatsappMessage.errorCode` conveys the [WhatsApp Business API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax) code.

### Meta error codes conveyed by webhooks

Listed below are some possible error codes conveyed by YCloud webhooks, that originated from Meta webhooks:

| Code | Description | Possible Solutions |
| - | - | - |
| `131000`<br />Something went wrong | Message failed to send due to an unknown error. | Try again. If the error persists, contact us to open a [Direct Support](https://business.facebook.com/direct-support) ticket. |
| `131026`<br />Message Undeliverable | Unable to deliver message. Reasons can include: <br /> <br />• The recipient phone number is not a WhatsApp phone number.<br />• Recipient has not accepted our new Terms of Service and Privacy Policy. <br />• Recipient using an outdated WhatsApp client.<br /> | Using a non-WhatsApp communication method, ask the WhatsApp user to:<br /> • Confirm that they can actually send a message to your WhatsApp business phone number.<br /> • Confirm that they have accepted our latest Terms of Service (Settings > Help, or Settings > Application information will prompt them to accept the latest terms/policies if they haven't done so already)<br /> • Update to the latest version of the WhatsApp client. |
| `131031`<br />Account has been locked | The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy, or we were unable to verify data included in the request against data set on the WhatsApp Business Account (e.g, the two-step pin included in the request is incorrect). | See the [Policy Enforcement](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/) document to learn about policy violations and how to resolve them. |
| `131047`<br />Re-engagement message | More than 24 hours have passed since the recipient last replied to the sender number. | Send the recipient a business-initiated message using a message template instead. |
| `131048`<br />Spam rate limit hit | 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. | Check your quality status in the WhatsApp Manager and see the [Quality-Based Rate Limits](https://developers.facebook.com/docs/whatsapp/messaging-limits#quality-rating-and-messaging-limits) documentation for more information. |
| `131049`<br /> | This message was not delivered to maintain healthy ecosystem engagement. | Do not retry immediately if you do receive this error code and suspect it is due to the limit. Instead, retry in increasing larger time increments until the message is delivered, since the limit may be in effect for differing periods of time.<br />See [Per-User Marketing Template Message Limits](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits) for additional information. |
| `131053`<br />Media upload error | Unable to upload the media used in the message. | We were unable to upload the media for one or more reasons, such as an [unsupported media type](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types). |
| `131050`<br />Message Undeliverable | Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business | |


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