WhatsApp Errors

Failed to submit messages to the Meta API

`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",
      "error_subcode": "2494071",
      "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 Meta 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 Meta 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",
      "error_subcode": "2494071",
      "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 Meta API

The whatsappApiError is exactly the Meta Cloud API Error. Listed below are some possible error codes that may be returned through the YCloud API.

Code	Description	HTTP Status
`2` API Service	Temporary due to downtime or due to being overloaded.	`503` Service Unavailable
`100` Invalid parameter	The request included one or more unsupported or misspelled parameters. Or the recipient phone number is not a WhatsApp phone number.	`400` Bad Request
`130429` Rate limit hit	Cloud API message throughput has been reached.	`429` Too Many Requests
`131000` Something went wrong	Message failed to send due to an unknown error.	`500` Internal Server Error
`131008` Required parameter is missing	The request is missing a required parameter.	`400` Bad Request
`131031` 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).	`403` Forbidden
`131056` (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.	`429` Too Many Requests
`133010` Phone number Not Registered	Business Phone number not registered on the WhatsApp Business Platform.	`400` 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 Meta 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:

Code	Description	HTTP Status
PARAM_INVALID	One or more of the parameters is invalid.	`400` Bad Request
PARAM_MISSING	One or more of the parameters is missing.	`400` Bad Request
BALANCE_INSUFFICIENT	The account balance is insufficient.	`403` Forbidden
WHATSAPP_BUSINESS_ACCOUNT_UNAVAILABLE	The WhatsApp business account is unavailable.	`403` Forbidden
WHATSAPP_PHONE_NUMBER_UNAVAILABLE	The WhatsApp business phone number is unavailable.	`403` 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.	`403` Forbidden

Meta failed to send messages

Not all of the error codes listed in Meta Cloud API Error page are returned through the YCloud API. Even if a message is successfully submitted to the Meta API, it may also fail to send. Meta notifies YCloud about these errors by 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 Meta API Error code.

Note: If you are using the Enqueue a WhatsApp message API, the message may fail due to a YCloud error. That is, the whatsappMessage.errorCode can also convey one of the YCloud Error Codes, such as BALANCE_INSUFFICIENT.

Meta-defined Error Codes conveyed by webhooks

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

Code	Description
`131000` Something went wrong	Message failed to send due to an unknown error.
`131026` Message Undeliverable	Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp phone number. Recipient has not accepted our new Terms of Service and Privacy Policy. Recipient using an old WhatsApp version; must use the following WhatsApp version or greater: Android: 2.21.15.15 SMBA: 2.21.15.15 iOS: 2.21.170.4 SMBI: 2.21.170.4 KaiOS: 2.2130.10 Web: 2.2132.6
`131031` 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).
`131047` Re-engagement message	More than 24 hours have passed since the recipient last replied to the sender number.
`131048` 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.
`131053` Media upload error	Unable to upload the media used in the message.