WhatsApp API Error Codes: Complete List Explained with Troubleshooting Steps
WhatsApp API error codes are numerical codes that identify and resolve the issues that users face while interacting with WhatsApp API solutions. As WhatsApp API is built on the graph API, solution providers or API integrators are suggested to handle the error logic using code and details to get clear values of the underlying issue. Using the codes, businesses are clear about the issue when messaging or connecting to the WhatsApp API and troubleshooting.
The following details a comprehensive list of WhatsApp API error codes, categorized in relevant buckets and with suggested troubleshooting steps. WhatsApp also lists a set of technical error codes for their cloud API service here.
a) Authorization Errors: Auth errors occur when the WhatsApp API system cannot verify the credentials or permissions of the user or application making requests.
Code | Description | Possible Solution |
0 | AuthException Meta is not able to authenticate the application user: Expired token changed access to data could be possible reasons . | Re-verify the app permissions or generate the access token here or check with your Solution Provider on the steps. |
3 | API Method Lack of necessary permissions to perform the API call or a misconfigured API call | Review API configuration or regenerate the access token. Contact your solution provider if using one. |
10 | Permission Denied Insufficient permissions to your application are not given,n or the access has been removed. Unapproved Phone Number: The phone number is not approved or allowed listed for the WhatsApp API account | Re-verify the API token for necessary app permission here. Refer to your solution provider for the necessary steps if you are using one. |
190 | Permission Denied The access token has expired, and access to the API is blocked | Obtain a new access token for the relevant app to ensure all permissions are taken. Your solution provider can guide you on the steps. |
200-299 | API Permission Errors Permission missing or revoked: Access to specific API features restricted | Verify the API token for obtaining the necessary app permission here. Refer to your Solution Provider for necessary steps if using their solution. |
b) Throttling Errors: When your application exceeds the allocated API call rate limit designated for your account.
Code | Description | Possible Solution |
4 | API has too many calls The application has exceeded the rate limit of API calls | Proactively monitor and optimize your API call rates. Proactively plan for API rate limit handling |
80007 | Rate limit issues WhatsApp API account reached its rate limit | Try later again or reduce #API Calls. |
130429 | Rate limit hit The message throughput limit has been breached. | You need to reduce the frequency at which messages are being sent, or you can retry again later |
131048 | Spam rate limit hit This is possible due to message volume restrictions on the phone number in the API account. This could be due to the previous history of spam flagging and messages being blocked by the recipient. | Check quality status in WhatsApp Manager and reduce message frequency. |
131056 | Pair rate limit hit A high number of messages in a short span of time that is sent from the sender’s phone number to a recipient with a particular phone number. | Wait and retry sending messages to the same recipient’s phone number. Sending messages to other phone numbers is not restricted. |
133016 | Phone number register/deregister limit breached WhatsApp limits #attempts to register or deregister to 10 in a 72-hour window | Wait for a while and try again after the blocked 72-hour window. |
c) Integrity Errors: This is related to a WhatsApp Platform policy violation that temporarily restricted certain actions for the business account.
Code | Description | Possible Solution |
368 | Temporarily Blocking due to policy violations The WhatsApp Business Account associated is restricted or blocked for violating a platform policy. | Review WhatsApp policies to understand and resolve violations, or consult your WhatsApp solution provider for resolution. |
130497 | Messaging restrictions in some countries: The WhatsApp Business Account is prohibited from messaging users in specific countries due to category restrictions or local policy | Check WhatsApp Geography and country-wise messaging restriction policy here. Consult WhatsApp support or solution provider for more details. |
131031 | Account Locked WhatsApp Business Account is restricted or completely disabled for violating the platform or commerce policy. It could be due to insufficient verification of messaging content or data. | Check messaging health guidelines or platform policy around spam enforcement. |
d) Message Template Errors: Issues related to the predefined structured message templates due to factors such as policy violation, prohibited content, rate limit, or formatting issues.
Code | Description | Possible Solution |
132000 | Template Param Count Mismatch The number of variable parameters in the message does not match the defined variable in the approved template | Review the message and refer to the template guidelines, ensuring all variable parameters are defined |
132001 | The template does not exist Either the template is not Approved, or it does not exist in the specific language. | Ensure that the message template is approved and the message name and language locale are correct. For more details, check details on the messaging template policy |
132005 | Translated Template exceeds the character limit Interactive templates with all the buttons, quick replies, and other string characters exceed the limits when translated. | Review the template content, simplify and reduce the character limit, and preferably use concise content. Review the template status for more action. |
132007 | Template Format Policy Violation The error occurs if the content includes non-supported characters, incorrect formatting, or other elements that do not comply with WhatsApp's guidelines. | Review the rejection reason and edit the template content again. |
132012 | Template parameter format mismatch Sending incorrect parameters (like image instead of video) in the template message that don’t match with the approved template format. | Ensure template parameters match the approved template format. Take the help of your WhatsApp solution provider if needed. |
132015 | Template Paused The Template has been paused due to poor quality rating, and the API account cannot send such template messages to their users. | Edit the template, improve the quality, and then try sending it again. |
132016 | Template Disabled If the template has been paused multiple times due to low quality, WhatsApp has disabled it. | It is suggested to create a new template, make changes in the content, and ensure quality content. |
e) Message Delivery Error: This relates to the failure of message delivery to the recipient due to content, configuration, or recipient-side issues.
Code | Description | Possible Solution |
131026 | Message Undeliverable Reasons could be -No Valid WhatsApp Number of the recipient -Recipient using an older version of the WhatsApp app -Recipient has not accepted WhatsApp new terms of service and privacy policy | The recipient has to accept WhatsApp T&Cs for service, register a WhatsApp account, or update the app version. |
131047 | Re-engagement Message Over 24 hours have passed since the recipient’s last reply. | Use a business-initiated message template to start a fresh conversation with the user again. |
131049 | Meta did not deliver the message Meta chose not to deliver the message to maintain healthy ecosystem engagement.
| This may be due to the per-user marketing message limit (read more details here). Retry after a certain time period. |
131051 | Unsupported message type Trying to send messages with a template format (media or other payload) not supported by WhatsApp. | Check supported message types in WhatsApp documentation. |
f) Media Errors: Errors in handling media files
Code | Description | Possible Solution |
131052 | Media download error WhatsApp is unable to download media included in the WhatsApp user's message. | It is suggested that the user is requested to send the media file on a channel other than WhatsApp. |
131053 | Media Upload Error WhatsApp was not able to upload the media for reasons such as
| Check the list of media file formats supported by WhatsApp |
g) WhatsApp Flows error: Issues related to the WhatsApp Flows feature
Code | Description | Possible Solution |
100 | A possible reason could be one of the many encountered during flow management
| Provide a valid and unique name, and confirm the specific ID, and valid URL as applied. Read more about Flows specific error handling |
139000 | Block by Integrity | Contact Whatsapp support or your solution provider for resolution. |
139001 | Flows cannot be updated Attempts to update the flows after publishing are not possible and will give you this error. | Clone the Flow, update the flow, and republish it. Use the new flow instead of the older one. |
139002 | Publishing Flows with incomplete details Publishing of flows with incomplete or improper details will result in this error. The reason could be one of the many
| Identify the missing details in the flows. Add the relevant details using the appropriate solution and then try publishing again. |
139003 | Deprecating a Flow Error encountered while attempting to deprecate a flow could be due to the below reasons
|
|
139004 | Cannot Delete a Published Flow Error while deleting a published flow as this is not allowed | Once a flow has been published it cannot be deleted, Try to deprecate it instead |
139006 | Flows Metrics Threshold There is not enough data to provide flow metrics | Wait for enough data in the flows to create metrics |
132068 | Flow Blocked Execution of the Whatsapp flows is blocked due to policy violations or user reports. | Review the flow and check for policy violations or excessive user reports. |
132069 | Flow throttled A specific WhatsApp flow has been temporarily limited in its ability to process messages, as 10 messages have already been sent in 1 hour | Monitor flow performance and correct the flow. Get assistance from WhatsApp support or your solution provider. |
h) Other Miscellaneous Errors:
Code | Description | Possible Solution |
131000 | Something went wrong Message sending failed due to an unknown error | Retry the request or contact support. Engage your WhatsApp Solution Provider if needed |
131005 | Access Denied WhatsApp has not given permission or revoked it |
|
131008 | The required parameter is missing: | See the endpoint's reference to determine which parameters are required. |
131009 | Parameter Value is invalid | Provide only supported parameters. Refer to this for reviewing the supported parameter types. |
131016 | Service Unavailable A WhatsApp service is temporarily unavailable | Contact your WhatsApp Solution Provider for more details or try to check the status of your WhatsApp Business Platform Status here |
131021 | The recipient cannot be the sender The sender and recipient have the same number | Use different numbers to send the message |
131037 | Display Name Missing An approved display name in the WhatsApp API is needed to send messages. Message cannot be sent if the display name is not approved | Try changing the display name and getting to approved using this guide |
131042 | Business Eligibility Payment Issue This was an error in the payment method linked to your WhatsApp Business Account. Possible reasons could include–Credit limit breach, No payment account, Payment or Credit line not set, etc. | Verify billing details and payment method in WhatsApp Manager to ensure the billing is set up properly. |
131045 | Incorrect Certificate Message sending is failing due to a business phone registration error | Try registering the phone number again and then retry |
131057 | Account in maintenance mode | Contact WhatsApp support or your solution provider for more details. |