The Cloud API is built on the Graph API, so if you are unfamiliar with handling Graph API error responses, see the Graph API 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.
Cloud API errors are returned either synchronously as a Graph API response, asynchronously via Webhook, or sometimes through both methods.
It is a good practice when working with Cloud API that you monitor both the Graph 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.
Cloud API errors can be surfaced in the following webhook objects:
Cloud API
entry.changes.value.errors
entry.changes.value.messages.errors
On-Premises API
errors
Error Response Syntax
{ "error": { "message": "<MESSAGE>", "type": "<TYPE>", "code": <CODE>, "error_data": { "messaging_product": "whatsapp", "details": "<DETAILS>" }, "error_subcode": <ERROR_SUBCODE> "fbtrace_id": "<FBTRACE_ID>" } }
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. |
{ "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" } }
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 . Ensure that the phone number used to set the business public key is allowlisted. |
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 |
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 Limitsection 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. |
Bad Request |
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. |
Bad Request |
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. |
Bad Request |
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. |
Bad Request |
(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 |
Bad Request |
Account register deregister rate limit exceeded |
Registration or Deregistration failed because there were too many attempts for this phone number in a short period of time |
The business phone number is being blocked because it has reached its registration/deregistration attempt limit. Try again once the number is unblocked. See "Limitations" in the Registration document. |
Bad Request |
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 |
Business account is restricted from messaging users in this country. |
The WhatsApp Business Account is restricted from messaging to users in certain countries. |
See WhatsApp Business Messaging Policy for details on allowed countries for messaging in your business category. |
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. You can also use the Health Status API , which may provide additional insight into the reason or reasons for the account lock. |
Forbidden |
1
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.
400
Bad Request
2
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.
503
Service Unavailable
33
Parameter value is not valid
The business phone number has been deleted.
Verify that the business phone number is correct.
400
Bad Request
100
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.
Ensure when setting the business public key, it is a valid 2048-bit RSA public key in PEM format .
Ensure there is no mismatch between the phone number id you are registering and a previously stored phone number id.
Ensure your parameter is under any length restriction for the type.
400
Bad Request
Message was not sent as part of an experiment .
400
Bad Request
131000
Something went wrong
Message failed to send due to an unknown error.
When setting a business public key , it either failed to calculate the signature, call the GraphQL endpoint, or the GraphQL endpoint returned an error.
Try again. If the error persists, open a Direct Support ticket.
500
Internal Server Error
131005
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 .
403
Forbidden
131008
Required parameter is missing
The request is missing a required parameter.
See the endpoint's reference to determine which parameters are required.
400
Bad Request
131009
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.
400
Bad Request
131016
Service unavailable
A service is temporarily unavailable.
Check the WhatsApp Business Platform Status page to see API status information before trying again.
500
Internal Server Error
131021
Recipient cannot be sender
Sender and recipient phone number is the same.
Send a message to a phone number different from the sender.
400
Bad Request
131026
Message Undeliverable
Unable to deliver message. Reasons can include:
Using a non-WhatsApp communication method, ask the WhatsApp user to:
400
Bad Request
131042
Business eligibility payment issue
There was an error related to your payment method.
See About Billing For Your WhatsApp Business Account and verify that you have set up billing correctly.
Common problems:
400
Bad Request
131045
Incorrect certificate
Message failed to send due to a phone number registration error.
Register the phone number before trying again.
500
Internal Server Error
131047
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.
400
Bad Request
131049
Meta chose not to deliver.
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.
See Per-User Marketing Template Message Limits for additional information.
400
Bad Request
131051
Unsupported message type
Unsupported message type.
See Messages for supported message types before trying again with a supported message type.
400
Bad Request
131052
Media download error
Unable to download the media sent by the user.
We were unable to download media included in the WhatsApp user's message. For more information, refer to the error.error_data.details
value in any messageswebhooks triggered when this message was received.
Ask the WhatsApp user to send you the media file using a non-WhatsApp method.
400
Bad Request
131053
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.
For more information, refer to the error.error_data.details
value in any messageswebhooks triggered when this message fails to send.
We recommend that you inspect any media files that are causing errors and confirm that they are in fact supported. For example, in UNIX you can use file inspection via the command line to determine its MIME type:
file -I rejected-file.mov
You can then confirm if its MIME type is supported. See Supported Media Types .
400
Bad Request
131057
Account in maintenance mode
Buiness Account is in maintenance mode
The WhatsApp Business Account is in maintenance mode. One reason for this could be that the account is undergoing a throughput upgrade.
500
Bad Request
132000
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.
400
Bad Request
132001
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 .
404
Not Found
132005
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 .
400
Bad Request
132007
Template Format Character Policy Violated
Template content violates a WhatsApp policy.
See Rejection Reasons to determine possible reasons for violation.
400
Bad Request
132012
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 .
400
Bad Request
132015
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
Bad Request
132016
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
Bad Request
132068
Flow is blocked
Flow is in blocked state.
Correct the Flow
400
Bad Request
132069
Flow is throttled
Flow is in throttled state and 10 messages using this flow were already sent in the last hour.
Correct the Flow
400
Bad Request
133000
Incomplete Deregistration
A previous deregistration attempt failed.
Deregister the number again before registering .
500
Internal Server Error
133004
Server Temporarily Unavailable
Server is temporarily unavailable.
Check the WhatsApp Business Platform Status
page to see API status information and check the response details
value before trying again.
503
Service Unavailable
133005
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:
400
Bad Request
133006
Phone number re-verification needed
Phone number needs to be verified before registering.
Verify the phone number before registering it.
400
Bad Request
133008
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 details
response value.
400
Bad Request
133009
Two step verification PIN Guessed Too Fast
Two-step verification PIN was entered too quickly.
Check the details
response value before trying again.
400
Bad Request
133010
Phone number Not Registered
Phone number not registered on the WhatsApp Business Platform.
Register the phone number before trying again.
400
Bad Request
133015
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.
400
Bad Request
135000
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.
400
Bad Request