At a glance
Overview
- 1 Open WhatsApp Suite → Campaign & History → open the campaign → Messages table.
- 2 Find the failed row’s error text or code, then open What this error means on that page — or use this guide.
- 3 Match the code (e.g. 131049) or the Meta message text. Meaning explains why; Action is what to do next.
- 4 Retryable failures (healthy ecosystem, rate limits, undeliverable) can be retried later or covered by Retarget Settings on Schedule Campaign.
Reference
Error codes
Same list as Campaign detail → What this error means.
| Code | Message | Meaning | What to do |
|---|---|---|---|
| Authorization errors | |||
| 0 | AuthException. We were unable to authenticate the app user. | App user could not be authenticated. | Access token may have expired or been invalidated. Get a new access token. |
| 3 | API Method. Capability or permissions issue. | Your app does not have the required capability or permissions. | Use the access token debugger to verify permissions. See Authentication and Authorization Errors. |
| 10 | Permission Denied. Permission is either not granted or has been removed. | Permission not granted or removed. | Use the access token debugger. See Authentication and Authorization Errors. For Flows, check allowlisted phone number. |
| 190 | Access token has expired. Your access token has expired. | WhatsApp connection (token) is invalid or expired. | Get a new access token. Reconnect your WhatsApp integration. |
| 200-299 | API Permission. Permission is either not granted or has been removed. | Permission not granted or removed. | Use the access token debugger. See Authentication and Authorization Errors. |
| 131005 | Access denied. Permission is either not granted or has been removed. | Your app does not have permission for this action. | Use access token debugger to verify permissions. See Authentication and authorization errors. |
| Integrity errors | |||
| 368 | Temporarily blocked for policies violations. The WABA has been restricted or disabled. | Your WhatsApp Business Account has been restricted or disabled for policy violation. | See the Policy Enforcement document to resolve policy violations. |
| 130497 | Business account is restricted from messaging users in this country. | Your WABA cannot message users in certain countries. | See WhatsApp Business Messaging Policy for allowed countries for your business category. |
| 131031 | Account has been locked. The WABA has been restricted or disabled for policy violation, or request data could not be verified (e.g. incorrect two-step pin). | Your WhatsApp Business Account is locked or restricted. | See Policy Enforcement. Use Health Status API for more insight. Fix policy issue or verify two-step pin. |
| Send template errors | |||
| 4 | API Too Many Calls. The app has reached its API call rate limit. | Your app is calling the API too often. | Check Application Rate Limit in App Dashboard. Try again later or reduce API call frequency. |
| 80007 | Rate limit issues. The WhatsApp Business Account has reached its rate limit. | Your business account has hit its messaging rate limit. | See WhatsApp Business Account Rate Limits. Try again later or reduce message frequency. |
| 130429 | Rate limit hit. Cloud API message throughput has been reached. | You are sending messages faster than the API allows. | See Throughput. Try again later or reduce send frequency. |
| 131048 | Spam rate limit hit. Restrictions on how many messages can be sent; too many were blocked or flagged as spam. | Your number has hit spam or quality limits. | Check quality status in WhatsApp Manager. See Template limits and Template quality. |
| 131056 | (Business Account, Consumer Account) pair rate limit hit. Too many messages from sender to same recipient in a short period. | You have messaged this user too often. | Wait and retry for the same number. You can still send to other numbers. |
| 133016 | Account register deregister rate limit exceeded. Too many registration/deregistration attempts for this phone number. | Phone number is blocked for too many registration attempts. | Try again once the number is unblocked. See Limitations in the Registration document. |
| 1 | API Unknown. Invalid request or possible server error. | Invalid request or server error. | Check WhatsApp Business Platform Status. Verify request format and endpoint requirements. |
| 2 | API Service. Temporary due to downtime or overload. | Service temporarily down or overloaded. | Check WhatsApp Business Platform Status before trying again. |
| 33 | Parameter value is not valid. The business phone number has been deleted. | The business phone number has been deleted. | Verify that the business phone number is correct. |
| 100 | Invalid parameter. Request included unsupported or misspelled parameters. | One or more parameters are wrong or not allowed. | Check endpoint reference for supported parameters and spelling. Check length limits. |
| 130472 | User's number is part of an experiment. Message was not sent as part of an experiment. | Message was not sent due to an experiment. | See Marketing Message Experiment. |
| 131000 | Something went wrong. Message failed to send due to an unknown error. | Unknown error. | Try again. If it persists, open a Direct Support ticket. |
| 131008 | Required parameter is missing. The request is missing a required parameter. | A required field was not sent. | See endpoint reference for required parameters. Include all required fields. |
| 131009 | Parameter value is not valid. One or more parameter values are invalid. | A value you sent is not allowed or wrong format. | Check endpoint reference for supported values. See Phone Numbers for adding a number to WABA. |
| 131016 | Service unavailable. A service is temporarily unavailable. | WhatsApp/Meta service is temporarily down or overloaded. | Check WhatsApp Business Platform Status page. Try again later. |
| 131021 | Recipient cannot be sender. Sender and recipient phone number is the same. | You are trying to send a message to your own business number. | Send to a different phone number than the sender. |
| 131026 | Message Undeliverable. Unable to deliver. Reasons: recipient not on WhatsApp; has not accepted Terms of Service and Privacy Policy; using old WhatsApp version; etc. | Message could not be delivered to this contact. | Ask user to confirm they can message you, accept latest terms (Settings > Help), and update to latest WhatsApp version. |
| 131037 | WhatsApp provided number needs display name approval before message can be sent. | Your 555 business number does not have an approved display name. | Change the business phone number's display name. See How to change your WhatsApp Business display name. |
| 131042 | Business eligibility payment issue. Error related to your payment method (e.g. no payment account, credit over limit, WABA deleted/suspended, timezone/currency not set, MessagingFor pending/declined). | Billing or payment setup problem for your WhatsApp Business Account. | See About Billing For Your WhatsApp Business Account. Verify payment account, credit line, and WABA status. |
| 131045 | Incorrect certificate. Message failed to send due to a phone number registration error. | Phone number registration problem. | Register the phone number before trying again. |
| 131047 | Re-engagement message. More than 24 hours have passed since the recipient last replied to the sender number. | 24-hour conversation window closed. You cannot send a free-form message. | Send the recipient a template message instead. |
| 131049 | Meta chose not to deliver. This message was not delivered to maintain healthy ecosystem engagement. | Per-user marketing limit: this user has received too many marketing messages (from all businesses). | If you receive this error and suspect it is due to the limit, wait at least 24 hours before resending the template message. The limit may be in effect for differing periods. See Per-User Marketing Template Message Limits for additional information. |
| 131050 | User has stopped receipt of marketing messages. This recipient has chosen to stop receiving marketing messages from your business. | User opted out of marketing from your business. | Do not retry. Subscribe to user_preferences webhook to be notified when users stop or resume marketing messages. |
| 131051 | Unsupported message type. | The message type you are sending is not supported. | See Messages for supported message types. Use a supported type. |
| 131052 | Media download error. Unable to download the media sent by the user. | Meta could not download media from the user's message. | Ask the user to send the media via a non-WhatsApp method. Check error.error_data.details in webhooks. |
| 131053 | Media upload error. Unable to upload the media used in the message (e.g. unsupported type). | Meta could not upload your media. | Check error_details in webhooks. Confirm media is supported. See Supported Media Types. |
| 131055 | Method not allowed. Only marketing template messages are supported. (MM API) | You attempted to send a non-template or non-marketing template. | Send again using a marketing template message. |
| 131057 | Account in maintenance mode. Business Account is in maintenance mode (e.g. throughput upgrade). | Your WABA is temporarily in maintenance. | Try again later. |
| 134011 | WhatsApp Payments terms of service has not been accepted. Message failed to send because WhatsApp Payments terms acceptance is pending for this WABA. | WhatsApp Payments terms not accepted for this WABA. | Accept the WhatsApp Payments terms of service using the link in the error message before trying again. |
| 134100 | Only marketing messages supported. You are only able to send marketing messages on this API. (MM API) | You attempted to send a utility or authentication template. | Only MARKETING templates are supported. Use a marketing template. |
| 134101 | Your template is still syncing. When you send from a template, syncing can take up to 10 minutes. (MM API) | New template has not finished syncing. | Wait 10 minutes and try again. |
| 134102 | Template unavailable for use. We could not complete Ad synchronization for the template, or you may not be eligible for MM API. (MM API) | Template sync failed or account not eligible. | Check eligibility status. If marketing_messages_lite_api_status is ONBOARDED and the problem persists, contact support. |
| 135000 | Generic user error. Message failed to send because of an unknown error with your request parameters. | Unknown error with your request parameters. | See endpoint reference for correct syntax. Contact customer support if the error continues. |
| 1752041 | Duplicate Request. Duplicate Request is thrown when a client has already been invited to onboard by any partner. | Client was already invited to onboard. | No action; duplicate invite. |
| Template creation errors | |||
| 132000 | Template Param Count Mismatch. The number of variable parameter values did not match the number of variable parameters defined in the template. | You sent the wrong number of variables for the template. | See Templates document. Include values for all parameters required by the template. |
| 132001 | Template does not exist. The template does not exist in the specified language or has not been approved. | Template missing or not approved for that language. | Ensure template is approved and template name and language locale are correct. See Templates document. |
| 132005 | Template Hydrated Text Too Long. Translated text is too long. | After filling variables, the message exceeds length limit. | Check WhatsApp Manager for template translation. See Template quality. |
| 132007 | Template Format Character Policy Violated. Template content violates a WhatsApp policy. | Template content violates a WhatsApp policy. | See Template review document for possible reasons for the violation. |
| 132012 | Template Parameter Format Mismatch. Variable parameter values are formatted incorrectly. | Variable values do not match the format specified in the template. | See Templates document for parameter formats. Send values in the correct format. |
| 132015 | Template is Paused. Template is paused due to low quality so it cannot be sent. | Template was paused by Meta for low quality. | Edit the template to improve quality and try again once it is approved. |
| 132016 | Template is Disabled. Template has been paused too many times due to low quality and is now permanently disabled. | Template can no longer be used. | Create a new template with different content. |
| 132068 | Flow is blocked. Flow is in blocked state. | Flow is blocked. | Correct the Flow. |
| 132069 | Flow is throttled. Flow is in throttled state and 10 messages using this flow were already sent in the last hour. | Flow is throttled. | Correct the Flow. |
| 2388040 | Character limit exceeded. A field in your template has exceeded the maximum character limit. | A template field is too long. | Refer to the error message for the affected field and character limits. |
| 2388047 | Message header format is incorrect. Your message header contains invalid formatting. | Template header format is invalid. | Refer to the error message for valid formatting. |
| 2388072 | Message body format is incorrect. Your message body contains invalid formatting. | Template body format is invalid. | Refer to the error message for valid formatting. |
| 2388073 | Message footer format is incorrect. Your message footer contains invalid formatting. | Template footer format is invalid. | Refer to the error message for valid formatting. |
| 2388293 | Parameters words ratio exceeds limit. This template has too many variables for its length. | Too many variables for the message length. | Reduce the number of variables or increase the message length. |
| 2388299 | Leading or trailing parameters not allowed. Variables cannot be at the start or end of the template. | Variables at start or end of template are not allowed. | Refer to the error message for valid formatting. |
| 2388019 | Message Template Limit Exceeded. You have exceeded the maximum number of message templates for this WABA (up to 250). | You have too many templates (max 250). | See Template limits. Remove or let expire some templates. |
| 200005 | Template insights unavailable. Template insights are not available yet for this WABA. | Template insights not available for this WABA. | Template insights cannot be enabled for this WABA at this time. |
| 200006 | Cannot disable template insights. Invalid operation. Template Insights cannot be disabled once enabled. | Template insights were already enabled. | Template insights cannot be disabled once enabled. |
| 200007 | Template Insights not enabled. Template Insights have not been enabled for this WABA. | Template insights are not enabled. | To enable, see Confirming template analytics. |
| Phone migration errors | |||
| 133000 | Incomplete Deregistration. A previous deregistration attempt failed. | Previous deregistration did not complete. | Deregister the number again before registering. |
| 133004 | Server Temporarily Unavailable. Server is temporarily unavailable. | Server is temporarily unavailable. | Check WhatsApp Business Platform Status and response details before trying again. |
| 133005 | Two step verification PIN Mismatch. Two-step verification PIN incorrect. | Two-step verification PIN is wrong. | Verify the PIN is correct. To reset, disable two-step verification then set a new PIN. See Two-step verification. |
| 133006 | Phone number re-verification needed. Phone number needs to be verified before registering. | Phone number must be verified before registering. | Verify and register the phone number. |
| 133008 | Too Many two step verification PIN Guesses. Too many two-step verification PIN guesses for this phone number. | Too many wrong PIN attempts. | Try again after the amount of time specified in the details response. |
| 133009 | Two step verification PIN Guessed Too Fast. Two-step verification PIN was entered too quickly. | PIN was entered too quickly. | Check the details value before trying again. |
| 133010 | Phone number Not Registered. Phone number not registered on the WhatsApp Business Platform. | Phone number is not registered. | Register the phone number before trying again. |
| 133015 | Please wait a few minutes before attempting to register this phone number. The number was recently deleted and deletion has not yet completed. | Number was recently deleted; wait for deletion to complete. | Wait 5 minutes before re-trying the request. |
Tips
- Error 131049 (healthy ecosystem) is Meta’s per-user marketing limit across all businesses — wait at least 24 hours before resending that marketing template to the same user.
- Error 131050 means the user opted out of marketing from your business — do not retry.
- To find contacts with undeliverable (131026) failures who never got a delivery, use Manage Contacts → Cleanup Tools → Undeliverable contacts — see the Cleanup Tools guide.
- These codes come from Meta’s WhatsApp Cloud API; UpScaleUp surfaces them so you can fix delivery, not because the app itself failed.