[Updated] WhatsApp API Error Codes: Explained with Troubleshooting Steps
WhatsApp API error codes identify issues like template issues, rate limits, authentication failures, and policy violations. WhatsApp Business API users need to troubleshoot issues using the relevant error codes.
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. Check that the phone number is properly registered and approved in your WhatsApp Business Account. Complete registration and approval if not done by your solution provider
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.
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
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.