Cloud API Error Codes
The Cloud API is built on the Graph API, so if you are unfamiliar with handling Graph API error responses, see Graph API's error handling documentation.
In general, we recommend that you build your app's error handling logic around code values and details payload properties. These properties and their values are more indicative of the underlying error.
Code titles, which do not have a dedicated property in API error response payloads, are included as part of the message value. However, we recommend that you do not rely on titles for your
error handling logic as titles will eventually be deprecated.
Webhooks
Some errors returned by our APIs are also reported via webhook. We
are gradually rolling out webhook reporting for all API error responses
over the next few months. You will receive these additional reports
automatically if you are subscribed to the messages webhook field. API errors can be surfaced in the following webhook objects:
Cloud API
entry.changes.value.errorsentry.changes.value.messages.errors
On-Premises API
errors
Error Response Contents
| Property | Value Type | Description |
|---|---|---|
| Integer | Error code. We recommend that you build your app's error handling around error codes instead of subcodes or HTTP response status codes. |
| String | Error description and a description of the most likely reason for the error. May also contain information on how to address the error, such as which parameter is invalid or what values are acceptable. |
| Integer | Deprecated. Will not be returned in v16.0+ responses. Graph API subcode. Not all responses will include a subcode, so we recommend that you build your error handling logic around |
| String | Trace ID you can include when contacting Direct Support. The ID may help us debug the error. |
| String | Combination of the error code and its title. For example: |
| String | Messaging product. This will always be the string |
| String | Error type. |
Sample Response
{ "error": { "message": "(#130429) Rate limit hit", "type": "OAuthException", "code": 130429, "error_data": { "messaging_product": "whatsapp", "details": "Message failed to send because there were too many messages sent from this phone number in a short period of time" }, "error_subcode": 2494055, "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam" } }
Error Codes
Authorization Errors
| Code | Description | Possible Solutions | HTTP Status Code |
|---|---|---|---|
AuthException | We were unable to authenticate the app user. | Typically this means the included access token has expired, been invalidated, or the app user has changed a setting to prevent all apps from accessing their data. We recommend that you get a new access token. |
Unauthorized |
API Method | Capability or permissions issue. | Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting. |
Internal Server Error |
Permission Denied | Permission is either not granted or has been removed. | Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting. |
Forbidden |
Access token has expired | Your access token has expired. |
Unauthorized | |
API Permission | Permission is either not granted or has been removed. | Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting. |
Forbidden |
Throttling Errors
| Code | Description | Possible Solutions | HTTP Status Code |
|---|---|---|---|
API Too Many Calls | The app has reached its API call rate limit. | Load the app in the App Dashboard and view the Application Rate Limit section to verify that the app has reached its rate limit. If it has, try again later or reduce the frequency or amount of API queries the app is making. |
Too many requests |
Rate limit issues | The WhatsApp Business Account has reached its rate limit. | See WhatsApp Business Account Rate Limits. Try again later or reduce the frequency or amount of API queries the app is making. |
Too many requests |
Rate limit hit | Cloud API message throughput has been reached. | The app has reached the API's throughput limit. See Throughput. Try again later or reduce the frequency with which the app sends messages. |
Too many requests |
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 documentation for more information. |
Too many requests |
(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 |
Too many requests |
Integrity Errors
| Code | Description | Possible Solutions | HTTP Status Code |
|---|---|---|---|
Temporarily blocked for policies violations | The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy. | See the Policy Enforcement document to learn about policy violations and how to resolve them. |
Forbidden |
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 document to learn about policy violations and how to resolve them. |
Forbidden |
Other Errors
| Code | Description | Possible Solutions | HTTP Status Code |
|---|---|---|---|
API Unknown | Invalid request or possible server error. | Check the WhatsApp Business Platform Status page to see API status information. If there are no server outages, check the endpoint reference and verify that your request is formatted correctly and meets all endpoint requirements. |
Bad Request |
API Service | Temporary due to downtime or due to being overloaded. | Check the WhatsApp Business Platform Status page to see API status information before trying again. |
Service Unavailable |
Parameter value is not valid | The business phone number has been deleted. | Verify that the business phone number is correct. |
Bad Request |
Invalid parameter | The request included one or more unsupported or misspelled parameters. | See the endpoint's reference to determine which parameters are supported and how they are spelled. |
Bad Request |
User's number is part of an experiment | Message was not sent as part of an experiment. |
Bad Request | |
Something went wrong | Message failed to send due to an unknown error. | Try again. If the error persists, open a Direct Support ticket. |
Internal Server Error |
Access denied | Permission is either not granted or has been removed. | Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting. |
Forbidden |
Required parameter is missing | The request is missing a required parameter. | See the endpoint's reference to determine which parameters are required. |
Bad Request |
Parameter value is not valid | One or more parameter values are invalid. | See the endpoint's reference to determine which values are supported for each parameter, and see Phone Numbers to learn how to add a phone number to a WhatsApp Business Account. |
Bad Request |
Service unavailable | A service is temporarily unavailable. | Check the WhatsApp Business Platform Status page to see API status information before trying again. |
Internal Server Error |
Recipient cannot be sender | Sender and recipient phone number is the same. | Send a message to a phone number different from the sender. |
Bad Request |
Message Undeliverable | Unable to deliver message. Reasons can include:
| Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp. |
Bad Request |
Business eligibility payment issue | Message failed to send because there were one or more errors related to your payment method. | See About Billing For Your WhatsApp Business Account and verify that you have set up billing correctly. Common problems:
|
Bad Request |
Incorrect certificate | Message failed to send due to a phone number registration error. | Register the phone number before trying again. |
Internal Server Error |
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. |
Bad Request |
Unsupported message type | Unsupported message type. | See Messages for supported message types before trying again with a supported message type. |
Bad Request |
Media download error | Unable to download the media sent by the user. | We were unable to download the media for one or more reasons, such as an unsupported media type. Refer to the |
Bad Request |
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. Refer to the For more reliable performance when sending media, refer to Media HTTP Caching and uploading the media. |
Bad Request |
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. | See Message Template Guidelines and make sure the request includes all of the variable parameter values that have been defined in the template. |
Bad Request |
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. Please ensure you follow message template guidelines. |
Not Found |
Template Hydrated Text Too Long | Translated text is too long. | Check the WhatsApp Manager to verify that your template has been translated. See Quality Rating and Template Status. |
Bad Request |
Template Format Character Policy Violated | Template content violates a WhatsApp policy. | See Rejection Reasons to determine possible reasons for violation. |
Bad Request |
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. See Message Template Guidelines. |
Bad Request |
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. |
Bad Request |
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. |
Bad Request |
Incomplete Deregistration | A previous deregistration attempt failed. | Deregister the number again before registering. |
Internal Server Error |
Server Temporarily Unavailable | Server is temporarily unavailable. | Check the WhatsApp Business Platform Status page to see API status information and check the response |
Service Unavailable |
Two step verification PIN Mismatch | Two-step verification PIN incorrect. | Verify that the two-step verification PIN included in the request is correct. To reset the two-step verification PIN:
|
Bad Request |
Phone number re-verification needed | Phone number needs to be verified before registering. | Verify the phone number before registering it. |
Bad Request |
Too Many two step verification PIN Guesses | Too many two-step verification PIN guesses for this phone number. | Try again after the amount of time specified in the |
Bad Request |
Two step verification PIN Guessed Too Fast | Two-step verification PIN was entered too quickly. | Check the |
Bad Request |
Phone number Not Registered | Phone number not registered on the Whatsapp Business Platform. | Register the phone number before trying again. |
Bad Request |
Please wait a few minutes before attempting to register this phone number | The phone number you are attempting to register was recently deleted, and deletion has not yet completed. | Wait 5 minutes before re-trying the request. |
Bad Request |
Generic user error | Message failed to send because of an unknown error with your request parameters. | See the endpoint's reference to determine if you are querying the endpoint using the correct syntax. Contact customer support if you continue receiving this error code in response. |
Bad Request |
Related Articles
API Documentation
Running an API in Postman is a straightforward process, but it becomes even more useful when you need to include custom headers and a specific JSON request body. In this guide, we'll walk you through the steps to run the WABA API using Postman with a ...How to create WooCommerce Secret API Keys?
Here are the steps you need to follow to generate the WooCommerce Secret API keys: 1. Go to WooCommerce Dashboard & reach the 'All Users' page First, go to your WooCommerce Admin Dashboard & under Users, pick all users. 2. 'Add New' user Next, ...How to automate API campaigns using Pabbly?
How Pabbly Works! Pabbly acts as an intermediate between two applications, transferring data from one app into another. Basically, it works on triggers & actions. A trigger on one app will lead to an action on the other app. Here are some trigger ...How to create WooCommerce Secret API Keys? (WooCommerce X Alendei 1)
To connect your WooCommerce store with Alendei, you need to do these two things: Get Secret Keys from WooCommerce Store Setup WooCommerce store in Alendei App In this doc, we've covered how to create the Secret API Keys needed to connect your ...Steps to apply for WhatsApp Business API
The next step to getting started with Alendei Platforms is applying for WhatsApp Business API. You must have a WhatsApp Business API account to get access to WhatsApp Broadcasting & all other Alendei Platforms features. That's why you must apply for ...