WhatsApp Errors

Receiving Errors: Synchronous and Asynchronous

WhatsApp API errors are returned either synchronously as a API response, asynchronously via Webhook, or sometimes through both methods.
It is a good practice when working with API that you monitor both the API response and the messages webhook for error handling. If you are subscribed to the messages webhook field, you will receive notification of errors as they occur for supported asynchronous error types.

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

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

{
  "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 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:

{
  "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. Listed below are some possible error codes that may be returned through the YCloud API.

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:

{
  "error": {
    "status": 400,
    "code": "PARAM_INVALID",
    "message": "Invalid E.146 phone number: +001",
    "target": "to",
    "docUrl": "https://docs.ycloud.com/v2/reference/errors#param_invalid",
    "requestId": "req_69UpMOaMHFrBMGZexYvUDw"
  }
}

The error.code is one of the YCloud server-defined error codes.

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

YCloud Error Codes conveyed by webhooks

If you are using the Enqueue a WhatsApp message 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, such as BALANCE_INSUFFICIENT.

Here are some possible errors:

Meta failed to send messages

Not all of the error codes listed in the WhatsApp Business Cloud API Error 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 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:

{
  "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 code.

Meta Error Codes conveyed by webhooks

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