Failed to submit messages to the Meta API
whatsappApiError
in response body
whatsappApiError
in response bodyYou 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
whatsappApiError
in webhook payloadIf 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. |