This page provides a complete reference of Meta WhatsApp Cloud API error codes that you may encounter when using OneChat. Each error includes a description, possible solution, and a link to the official Meta documentation when available.
Tip: Use the table of contents or search (Ctrl+F) to quickly find a specific error code. You can also bookmark the direct link to any error using the #error-{code} anchor in the URL.
Need help? If you encounter an error not listed here or need further assistance, contact our support team at
soporte@onechat.com.do.
Integrity Errors
These errors are related to policy violations, account restrictions, or account locks. They are returned with a 403 - Forbidden HTTP status code.
Error 368
|
|
| Title |
Temporarily blocked for policies violations |
| Description |
The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy. |
| Solution |
See the Policy Enforcement document to learn about policy violations and how to resolve them. Contact OneChat support for further assistance. |
| Meta Docs |
Policy Enforcement |
Error 130497
|
|
| Title |
Restricted region |
| Description |
The WhatsApp Business Account is restricted from messaging to users in certain countries. |
| Solution |
See WhatsApp Business Messaging Policy for details on allowed countries for messaging in your business category. Cross-country messaging can be unlocked by completing a scaling path to reach the 2,000 messaging limit tier. |
| Meta Docs |
WhatsApp Business Messaging Policy |
Error 131031
|
|
| Title |
Account has been locked |
| Description |
The WhatsApp Business Account has been restricted or disabled for violating a platform policy, or Meta was unable to verify data included in the request (e.g., the two-step PIN included in the request is incorrect). |
| Solution |
1. Disable 2FA. 2. Re-register the number. 3. Enable 2FA again. See the Policy Enforcement document for more details. |
| Meta Docs |
Policy Enforcement |
Messaging Errors
These errors occur when sending or receiving messages through the WhatsApp Cloud API.
Error 1
|
|
| Title |
API Unknown |
| Description |
Invalid request or possible server error. |
| Solution |
Check the WhatsApp Business Platform Status page. If there are no server outages, verify that your request is formatted correctly. |
| Can Retry |
Yes |
| Meta Docs |
WhatsApp Business Platform Status |
Error 2
|
|
| Title |
API Service |
| Description |
Temporary due to downtime or due to being overloaded. |
| Solution |
Check the WhatsApp Business Platform Status page before trying again. |
| Can Retry |
Yes |
| Meta Docs |
WhatsApp Business Platform Status |
Error 33
|
|
| Title |
Parameter value is not valid (deleted number) |
| Description |
The business phone number has been deleted. |
| Solution |
Verify that the business phone number is correct. |
Error 100
|
|
| Title |
Invalid parameter |
| Description |
The request included one or more unsupported or misspelled parameters. For Marketing Messages: Message must be a template message. |
| Solution |
Review the API documentation to make sure you are sending the correct data and structure. Contact OneChat support if the error persists. |
Error 131000
|
|
| Title |
Something went wrong |
| Description |
Message failed to send due to an unknown error. |
| Solution |
Try again. If the error persists, contact OneChat support. |
| Can Retry |
Yes |
Error 131005
|
|
| Title |
Access denied |
| Description |
Permission is either not granted or has been removed. |
| Solution |
Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. |
Error 131008
|
|
| Title |
Required parameter is missing |
| Description |
The request is missing a required parameter. |
| Solution |
Review the API documentation to make sure you are sending all required parameters. |
| Meta Docs |
Messages API Reference |
Error 131009
|
|
| Title |
Parameter value is not valid |
| Description |
One or more parameter values are invalid. |
| Solution |
Review the API documentation to make sure you are sending the correct data and structure. Contact OneChat support if the error persists. |
Error 131016
|
|
| Title |
Service unavailable |
| Description |
A service is temporarily unavailable. |
| Solution |
Check the WhatsApp Business Platform Status page before trying again. |
| Can Retry |
Yes |
| Meta Docs |
WhatsApp Business Platform Status |
Error 131021
|
|
| Title |
Recipient cannot be sender |
| Description |
Sender and recipient phone number is the same. |
| Solution |
Send a message to a phone number different from the sender. |
Error 131026
|
|
| Title |
Message undeliverable |
| Description |
Unable to deliver message. This may happen because the contact phone number is not registered on WhatsApp, the recipient has blocked you, or the message was rejected by WhatsApp for delivery policy reasons. Note: Meta does not always disclose the underlying cause of this error due to privacy and policy reasons. |
| Solution |
Verify the contact phone number is valid and exists on WhatsApp. Using a non-WhatsApp communication method, ask the user to: confirm they can send a message to your business number, check that your number is not blocked, accept Meta's latest Terms of Service, and update to the latest version of WhatsApp. |
Error 131037
|
|
| Title |
Display name approval needed |
| Description |
The 555 business phone number used to send the request does not have an approved display name. |
| Solution |
Change the 555 business phone number's display name. |
| Meta Docs |
How to change your WhatsApp Business display name |
Error 131042
|
|
| Title |
Payment issue |
| Description |
WhatsApp rejected the message delivery due to an error in your payment method. Common problems: payment method not registered in Meta Business, credit line is empty or over limit. |
| Solution |
Go to Meta Business Manager and make sure your WhatsApp Business Account payment method is set up correctly and has funds. |
| Meta Docs |
Billing |
Error 131045
|
|
| Title |
Incorrect certificate |
| Description |
Message failed to send due to a phone number registration error. |
| Solution |
Register the phone number before trying again. |
Error 131047
|
|
| Title |
Out of 24h response window |
| Description |
More than 24 hours have passed since the recipient last replied and the free response window has expired. |
| Solution |
To re-open the conversation, send the user an approved template message. |
Error 131049
|
|
| Title |
Meta chose not to deliver |
| Description |
This message was rejected by WhatsApp due to sending too many marketing messages to the same user in a short period of time. This is a Meta limitation to maintain healthy ecosystem engagement. |
| Solution |
Wait at least 24 hours before sending a marketing template message to the same user. Do not retry immediately — the limit may be in effect for varying periods of time. This feature is deployed for all businesses and there is no whitelisting available. This limit is not active in the European Economic Area, United Kingdom, Japan, or South Korea. |
| Meta Docs |
Per-User Marketing Template Message Limits |
Error 131050
|
|
| Title |
Opted-out from marketing messages |
| Description |
Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business. |
| Solution |
Do not retry sending messages to this user as they will not be received. |
Error 131051
|
|
| Title |
Unsupported message type |
| Description |
The message format is not supported by the WhatsApp Cloud API. This typically happens when receiving interactive button messages that are not sent as approved templates, or when sending unsupported media types. This is a limitation of Meta's Cloud API. |
| Solution |
Use approved message templates with buttons instead of interactive button messages. Templates are the officially supported method by Meta for sending structured messages with buttons. See the Messages API reference for supported message types. |
| Meta Docs |
Messages API Reference |
Error 131052
|
|
| Title |
Media download error |
| Description |
Unable to download the media sent by the user. |
| Solution |
Ask the WhatsApp user to send you the media file using a non-WhatsApp method. |
Error 131053
|
|
| Title |
Media upload error |
| Description |
Unable to upload the media used in the message. This may be caused by an unsupported media type. |
| Solution |
Inspect any media files that are causing errors and confirm that they are supported. |
| Meta Docs |
Supported Media Types |
Error 131055
|
|
| Title |
Method not allowed (Marketing Messages API) |
| Description |
Only marketing template messages are supported. You may have attempted to send a non-template message, or an authentication or utility template. |
| Solution |
Try sending again using a marketing template message. |
Error 131057
|
|
| Title |
Account in maintenance mode |
| Description |
The WhatsApp Business Account is in maintenance mode. One reason for this could be that the account is undergoing a throughput upgrade. |
| Solution |
Try again later. |
| Can Retry |
Yes |
Error 135000
|
|
| Title |
Generic user error |
| Description |
Message failed to send because of an unknown error with your request parameters. |
| Solution |
Review the API documentation to make sure you are sending the correct data and structure. Contact OneChat support if the error persists. |
Rate Limit Errors
These errors occur when API rate limits or message throughput limits are exceeded.
Error 4
|
|
| Title |
WhatsApp API limit exceeded |
| Description |
Number API calls rate limit has been reached. |
| Solution |
Implement request throttling or exponential backoff. Contact OneChat support if you need a higher rate limit. |
| Can Retry |
Yes |
Error 80007
|
|
| Title |
WABA rate limit exceeded |
| Description |
The WhatsApp Business Account has reached its rate limit. |
| Solution |
Verify your business in Meta to increase your rate limit. Try again later or reduce the frequency of API queries. |
| Can Retry |
Yes |
Error 130429
|
|
| Title |
Throughput rate limit hit |
| Description |
Cloud API message throughput has been reached. |
| Solution |
Try again later or reduce the frequency with which messages are sent. Contact OneChat support if the issue persists. |
| Can Retry |
Yes |
Error 131048
|
|
| Title |
Spam protection |
| Description |
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. |
| Solution |
Check your quality status in the WhatsApp Manager. |
| Can Retry |
Yes |
Error 131056
|
|
| Title |
Too many messages sent |
| Description |
Too many messages sent from the sender phone number to the same recipient phone number in a short period of time. |
| Solution |
Wait and retry the operation. |
| Can Retry |
Yes |
Template Errors
These errors are related to message template creation, formatting, or sending.
Error 132000
|
|
| Title |
Template Param Count Mismatch |
| Description |
The number of variable parameter values included in the request did not match the number of variable parameters defined in the template. |
| Solution |
Make sure the request includes values for all of the parameters required by the template. |
| Meta Docs |
Message Template Guidelines |
Error 132001
|
|
| Title |
Template does not exist |
| Description |
The template does not exist in the specified language or the template has not been approved. |
| Solution |
Make sure your template has been approved and the template name and language locale are correct. |
| Meta Docs |
Message Template Guidelines |
Error 132005
|
|
| Title |
Template Hydrated Text Too Long |
| Description |
Translated text is too long. |
| Solution |
Check the WhatsApp Manager to verify that your template has been translated correctly. |
Error 132007
|
|
| Title |
Template Format Policy Violated |
| Description |
Template content violates a WhatsApp policy. |
| Solution |
Review the template content and ensure it complies with Meta's policies. |
| Meta Docs |
Message Template Guidelines |
Error 132012
|
|
| Title |
Template Parameter Format Mismatch |
| Description |
Variable parameter values formatted incorrectly. The variable parameter values included in the request are not using the format specified in the template. |
| Solution |
Review the template parameter format requirements. |
Error 132015
|
|
| Title |
Template is Paused |
| Description |
Template is paused due to low quality so it cannot be sent in a template message. |
| Solution |
Edit the template to improve its quality and try again once it is approved. |
Error 132016
|
|
| Title |
Template is Disabled |
| Description |
Template has been paused too many times due to low quality and is now permanently disabled. |
| Solution |
Create a new template with different content. |
Error 2388019
|
|
| Title |
Message Template Limit Exceeded |
| Description |
You have exceeded the maximum number of message templates you can have for this WhatsApp Business Account. |
| Solution |
A WhatsApp Business Account can have up to 250 message templates. Remove unused templates to make room for new ones. |
| Meta Docs |
Template limits |
Error 2388040
|
|
| Title |
Character limit exceeded |
| Description |
A field in your template has exceeded the maximum character limit allowed. |
| Solution |
Refer to the error message for specific details on the affected field and its character limits. |
Error 2388047
|
|
| Title |
Message header format is incorrect |
| Description |
Your message header contains invalid formatting. |
| Solution |
Refer to the error message for specific details on valid formatting. |
Error 2388072
|
|
| Title |
Message body format is incorrect |
| Description |
Your message body contains invalid formatting. |
| Solution |
Refer to the error message for specific details on valid formatting. |
Error 2388073
|
|
| Title |
Message footer format is incorrect |
| Description |
Your message footer contains invalid formatting. |
| Solution |
Refer to the error message for specific details on valid formatting. |
Error 2388293
|
|
| Title |
Parameters words ratio exceeds limit |
| Description |
This template has too many variables for its length. |
| Solution |
Reduce the number of variables or increase the message length. |
Error 2388299
|
|
| Title |
Leading or trailing parameters not allowed |
| Description |
Variables cannot be at the start or end of the template. |
| Solution |
Move variables so they are not at the beginning or end of the template text. |
Flow Errors
These errors are related to WhatsApp Flows.
Error 132068
|
|
| Title |
Flow is blocked |
| Description |
Flow is in blocked state. |
| Solution |
Review and correct the Flow in Meta Business Manager. |
Error 132069
|
|
| Title |
Flow is throttled |
| Description |
Flow is in throttled state and 10 messages using this flow were already sent in the last hour. |
| Solution |
Wait before sending additional messages using this Flow. |
Phone Registration Errors
These errors occur during phone number registration, migration, or verification.
Error 2388001
|
|
| Title |
Phone verification failed |
| Description |
Certificate can be downloaded only after confirming ownership of a phone number that is being migrated. Or two-step authentication must be disabled. |
| Solution |
Register and verify the number. Ensure two-step verification is disabled. |
| Meta Docs |
Registering Phone Numbers |
Error 2388012
|
|
| Title |
Phone number already exists |
| Description |
The phone number you are trying to migrate is already present in your WhatsApp account. |
| Solution |
Try again with a phone number that is not already present in your WhatsApp account. |
Error 2388091
|
|
| Title |
Phone number not eligible |
| Description |
Phone ownership verification APIs are not available for this use case. |
| Solution |
Register and verify the number. |
Error 2388103
|
|
| Title |
Cannot migrate phone number |
| Description |
There was an error migrating this phone number or webhooks have not been set up for the destination account. |
| Solution |
Subscribe your app to webhooks on the destination WhatsApp Business Account. Ensure business verification is completed. |
Error 133000
|
|
| Title |
Incomplete Deregistration |
| Description |
A previous deregistration attempt failed. |
| Solution |
Deregister the number again before registering. |
Error 133004
|
|
| Title |
Server Temporarily Unavailable |
| Description |
Server is temporarily unavailable. |
| Solution |
Check the WhatsApp Business Platform Status page and try again later. |
| Can Retry |
Yes |
Error 133005
|
|
| Title |
Two step verification PIN Mismatch |
| Description |
Two-step verification PIN incorrect. |
| Solution |
Verify that the two-step verification PIN is correct. To reset the PIN, disable two-step verification, then set a new PIN. |
Error 133006
|
|
| Title |
Phone number re-verification needed |
| Description |
Phone number needs to be verified before registering. |
| Solution |
Verify and register the phone number. |
Error 133008
|
|
| Title |
Too Many PIN Guesses |
| Description |
Too many two-step verification PIN guesses for this phone number. |
| Solution |
Try again after the amount of time specified in the response. |
| Can Retry |
Yes |
Error 133009
|
|
| Title |
PIN Guessed Too Fast |
| Description |
Two-step verification PIN was entered too quickly. |
| Solution |
Wait before trying again. |
| Can Retry |
Yes |
Error 133010
|
|
| Title |
Phone number Not Registered |
| Description |
Phone number not registered on the WhatsApp Business Platform. |
| Solution |
Register the phone number before trying again. |
Error 133015
|
|
| Title |
Registration wait needed |
| Description |
The phone number you are attempting to register was recently deleted, and deletion has not yet completed. |
| Solution |
Wait 5 minutes before re-trying the request. |
| Can Retry |
Yes |
Error 133016
|
|
| Title |
Register/deregister rate limit exceeded |
| Description |
Registration or deregistration failed because there were too many attempts for this phone number in a short period of time. |
| Solution |
Wait until the number is unblocked and try again. |
| Can Retry |
Yes |
Account and Business Errors
These errors are related to account status, experiments, payments, and business account operations.
Error 130472
|
|
| Title |
User's number is part of an experiment |
| Description |
Message was not sent as part of an experiment. |
| Solution |
See Meta's Marketing Message Experiment documentation. |
| Meta Docs |
Marketing Message Experiment |
Error 134011
|
|
| Title |
WhatsApp Payments terms of service not accepted |
| Description |
Message failed to send because WhatsApp Payments terms of service acceptance is pending for this WhatsApp Business Account. |
| Solution |
Accept the WhatsApp Payments terms of service using the link provided in the error message. |
Error 2494100
|
|
| Title |
Account in maintenance mode |
| Description |
The business phone number is in maintenance mode. |
| Solution |
Try again in a few minutes. |
| Can Retry |
Yes |
Error 2593079
|
|
| Title |
WABA marked for migration |
| Description |
This WABA has already been marked for migration to a different solution ID. The OBO account ownership model is now deprecated. |
| Solution |
Contact OneChat support. |
Error 2593085
|
|
| Title |
Invalid WABA for OBO Mobility |
| Description |
The WABA is not eligible for OBO ownership transfer. The OBO account ownership model is now deprecated. |
| Solution |
Contact OneChat support. |
Error 2593107
|
|
| Title |
Synchronization request limit exceeded |
| Description |
You have exceeded the maximum number of times to call the synchronization API for this phone number. |
| Solution |
You can only call this endpoint once to synchronize contacts and once to synchronize messaging history. |
Error 2593108
|
|
| Title |
Synchronization request outside allowed time window |
| Description |
Synchronization request can only be made within 24 hours of onboarding. |
| Solution |
Disconnect the number and re-connect it to initiate a new synchronization window. |
Marketing Messages API Errors
These errors are specific to the Marketing Messages API.
Error 134100
|
|
| Title |
Only marketing messages supported |
| Description |
You are only able to send marketing messages on this API. You are attempting to send a utility or authentication template. |
| Solution |
Only templates categorized as MARKETING are supported on the Marketing Messages API. |
Error 134101
|
|
| Title |
Template still syncing |
| Description |
When you send a message from a template, the template syncing process can take up to 10 minutes to complete. |
| Solution |
Wait a few minutes, and then try sending your message again. |
| Can Retry |
Yes |
Error 134102
|
|
| Title |
Template unavailable for use |
| Description |
We were unable to complete Ad synchronization for the template you are attempting to send, or you may not be eligible for the Marketing Messages API. |
| Solution |
Check your eligibility status or contact Meta's customer support. |
Error 1752041
|
|
| Title |
Duplicate onboarding request |
| Description |
A duplicate request is thrown when a client has already been invited to onboard by any partner. |
| Solution |
If you receive this error, no further action is required — the onboarding request has already been made. |
