Developer Reference
WhatsApp Business API Error Codes – Meaning & Fixes
86 common WhatsApp Cloud API error codes explained in simple words, with what each one means and how to fix it.
Basics
How WhatsApp API errors work
Understand the error before you fix it.
Two placesErrors come back in the API response right away, through the messages webhook later, or both – so watch both.
Use the codeBuild your error handling on the numeric code and the details text, not on the title – titles will be removed over time.
Read the detailsThe details field explains the most likely reason and often which parameter is wrong.
fbtrace_idShare this trace ID with Meta support when you need help with a specific error.
Subcodes are olderror_subcode is deprecated and isn’t returned in newer API versions.
Check status firstFor server-type errors, check the WhatsApp Business Platform status page before debugging.
Most searched
Top errors and quick fixes
Error 190 · Access token expiredGet a new access token – use a permanent system-user token for production.
Error 130429 · Message throughput reachedSend more slowly or spread campaigns over time.
Error 131048 · Spam rate limitCheck quality in WhatsApp Manager and message only opted-in customers.
Error 131026 · Message undeliverableAsk the user (by another channel) to check they can message you, accept the latest terms and update WhatsApp.
Error 131047 · 24-hour window closedSend an approved template message instead.
Error 131049 · Not delivered for healthy engagementWait at least 24 hours before trying that user again.
Error 132000 · Template parameter count mismatchSend a value for every template variable.
Error 132001 · Template doesn’t existCheck the name, language code and approval status.
| Code | Type | What it means | How to fix |
|---|---|---|---|
| 0 | Authorization | Unable to authenticate The access token has expired, was invalidated, or the user blocked app access. | Generate a new access token. |
| 3 | Authorization | Capability or permissions issue Your app does not have the permission this endpoint needs. | Check the token in Meta’s access token debugger and add the missing permission. |
| 10 | Authorization | Permission not granted or removed A required permission is missing, or the account is not eligible for this API. | Verify permissions in the token debugger and check eligibility. For Flows with endpoint, make sure the phone number used for the public key is allowlisted. |
| 190 | Authorization | Access token expired The access token is no longer valid. | Get a new access token – use a permanent system-user token for production. |
| 200 | Authorization | No access token provided The request had no token (some GET endpoints reply “Provide valid app ID”). | Include a valid access token in the request. |
| 200–299 | Authorization | API permission error A permission is not granted or was removed. | Check the token in the access token debugger and grant the required permissions. |
| 368 | Integrity | Account restricted for policy violation The WhatsApp Business Account was restricted or disabled for breaking a platform policy. | Read Meta’s Policy Enforcement guidance, fix the issue and follow the steps shown in WhatsApp Manager. |
| 130497 | Integrity | Messaging restricted in some countries Your business category is not allowed to message users in certain countries. | Check the WhatsApp Business Messaging Policy for allowed countries in your category. |
| 131031 | Integrity | Account locked The account was restricted for a policy violation, or data in the request (like the two-step PIN) did not match. | Check WhatsApp Manager and the Health Status API for the reason, and correct the data or policy issue. |
| 2388039 | Template creation | Template status can’t be changed You tried to edit a template whose status can’t change, for example while it is in review. | Wait until it is approved or rejected before editing. Templates also have a daily edit limit. |
| 2388040 | Template creation | Character limit exceeded A template field is longer than allowed. | Shorten the field mentioned in the error message. |
| 2388047 | Template creation | Header format incorrect The template header has invalid formatting. | Fix the header format as described in the error message. |
| 2388072 | Template creation | Body format incorrect The template body has invalid formatting. | Fix the body format as described in the error message. |
| 2388073 | Template creation | Footer format incorrect The template footer has invalid formatting. | Fix the footer format as described in the error message. |
| 2388293 | Template creation | Too many variables for the length The template has too many variables compared to its text. | Remove some variables or add more fixed text. |
| 2388299 | Template creation | Variables at start or end A template can’t start or end with a variable. | Add text before the first variable and after the last one. |
| 2388019 | Send template | Template limit exceeded The account already has the maximum number of templates (up to 250). | Delete unused templates before creating new ones. |
| 2388012 | Phone migration | Number already in your account The phone number you want to migrate is already in this WhatsApp account. | Use a number that isn’t already in the account. |
| 2388091 / 2388093 | Phone migration | Number not eligible for migration verification Ownership verification APIs aren’t available because the number isn’t being migrated. | Register and verify the number normally. |
| 2388103 | Phone migration | Cannot migrate phone number Several reasons share this code: migration not supported on the new account model, the number can be added directly, the display name isn’t approved (or has a pending change), or a general migration error. | Read the error message: add the number directly, get the display name approved, or try again later / contact support. |
| 2494100 | Phone migration | Account in maintenance mode The business phone number is in maintenance mode. | Try again in a few minutes. |
| 200005 | Template insights | Template insights unavailable Template insights aren’t available yet for this account. | Try again later – they can’t be enabled right now. |
| 200006 | Template insights | Cannot disable template insights Template insights can’t be turned off once enabled. | No action needed – insights stay enabled. |
| 200007 | Template insights | Template insights not enabled Insights aren’t enabled for this WhatsApp Business Account. | Enable template analytics first. |
| 2593079 | Business account | WABA already marked for migration The account is already marked for migration to another solution. The OBO model is deprecated. | Contact support. |
| 2593085 | Business account | Invalid WABA for OBO transfer The account can’t be transferred under the deprecated OBO model (already customer-owned or request not accepted). | Contact support. |
| 2593107 | Synchronization | Sync API limit reached Contacts and chat history can each be synced only once per number. | Offboard the business app user and onboard them again. |
| 2593108 | Synchronization | Sync window expired Sync must be started within 24 hours of onboarding. | Offboard the user and onboard them again, then sync within 24 hours. |
| 4 | Throttling | App API rate limit Your app reached its API call rate limit. | Check Application Rate Limit in the App Dashboard, slow down and retry later. |
| 80007 | Throttling | WABA rate limit The WhatsApp Business Account reached its rate limit. | Reduce how often you call the API and retry later. |
| 130429 | Throttling | Message throughput reached Your number hit the Cloud API sending speed limit. | Send more slowly or spread campaigns over time. |
| 131048 | Throttling | Spam rate limit Sending is restricted because many earlier messages were blocked or reported. | Check quality in WhatsApp Manager and message only opted-in customers. |
| 131056 | Throttling | Too many messages to one user Too many messages to the same recipient in a short time. | Wait before messaging that number again. Other numbers are not affected. |
| 133016 | Throttling | Register/deregister limit Too many registration or deregistration attempts for this number. | Wait until the number is unblocked, then try again. |
| 131064 | Throttling | Limit due to template classification violations Messaging is limited because templates were categorised incorrectly. | Fix template categories. The limit lifts after the enforcement period. |
| 1 | Other | Invalid request or server error The request is invalid or there is a server problem. | Check the WhatsApp Business Platform status page and your request format. |
| 2 | Other | Temporary downtime The service is down or overloaded. | Check the status page and retry later. |
| 33 | Other | Phone number deleted The business phone number has been deleted. | Check that you are using the correct phone number ID. |
| 100 | Other | Invalid parameter A parameter is unsupported, misspelled, too long, or the phone number ID doesn’t match. | Compare your request with the endpoint reference. For Flows, use a valid 2048-bit RSA public key in PEM format. |
| 130403 | Other | You blocked this user Your business has blocked this WhatsApp user. | Don’t retry. Unblock the user to message them again. |
| 130472 | Other | Not sent – marketing experiment The message wasn’t sent as part of Meta’s marketing message experiment. | No action needed for this user. |
| 131000 | Other | Unknown error The message failed for an unknown reason. | Retry. If it keeps happening, open a support ticket. |
| 131005 | Other | Access denied A permission is not granted or was removed. | Check permissions in the token debugger. |
| 131008 | Other | Required parameter missing A required field is missing from the request. | Add the missing field. |
| 131009 | Other | Parameter value not valid One or more values are invalid (for example the phone number). | Check allowed values and the phone number setup. |
| 131016 | Other | Service temporarily unavailable A service is down for a short time. | Check the status page and retry. |
| 131021 | Other | Sender and recipient are the same You tried to message your own business number. | Send to a different number. |
| 131026 | Other | Message undeliverable The number isn’t on WhatsApp, the user hasn’t accepted new terms, or uses a very old app version. | Ask the user (by another channel) to check they can message you, accept the latest terms and update WhatsApp. |
| 131037 | Other | Display name not approved (555 number) The 555 test number doesn’t have an approved display name. | Change or get approval for the display name. |
| 131042 | Other | Payment method issue There is a billing problem – no payment account, credit limit reached, account suspended, or timezone/currency not set. | Check billing setup for your WhatsApp Business Account. |
| 131045 | Other | Phone registration error The phone number isn’t registered correctly. | Register the phone number and try again. |
| 131047 | Other | 24-hour window closed More than 24 hours passed since the customer last replied. | Send an approved template message instead. |
| 131049 | Other | Not delivered for healthy engagement Meta didn’t deliver this marketing message to keep engagement healthy (per-user limit). | Wait at least 24 hours before trying that user again. |
| 131050 | Other | User stopped marketing messages The user chose to stop marketing messages from your business. | Don’t retry. Subscribe to the user_preferences webhook to track changes. |
| 131051 | Other | Unsupported message type The message type isn’t supported. | Use a supported type. |
| 131052 | Other | Media download error The media the user sent couldn’t be downloaded. | Ask the user to send the file another way. |
| 131053 | Other | Media upload error Your media couldn’t be uploaded, often because of an unsupported type. | Check the file’s real MIME type and use a supported format. |
| 131057 | Other | Account in maintenance mode The account is under maintenance, for example during a throughput upgrade. | Wait and retry. |
| 131063 | Other | Marketing templates disabled on Cloud API Marketing templates are turned off for your Cloud API setup. | Send through the Marketing Messages API, or re-enable marketing templates on Cloud API. |
| 132000 | Other | Template parameter count mismatch The number of variables doesn’t match the template. | Send a value for every template variable. |
| 132001 | Other | Template doesn’t exist Wrong template name/language, or the template isn’t approved. | Check the name, language code and approval status. |
| 132005 | Other | Translated text too long The text with variables filled in is too long. | Check the template translation in WhatsApp Manager and shorten values. |
| 132007 | Other | Template violates a policy The template content breaks a WhatsApp policy. | Review the template rules and change the content. |
| 132012 | Other | Parameter format mismatch Variable values don’t match the format set in the template. | Use the expected format for each variable. |
| 132015 | Other | Template paused The template was paused for low quality. | Edit it to improve quality and send after it’s approved again. |
| 132016 | Other | Template permanently disabled The template was paused too many times. | Create a new template with different content. |
| 132068 | Other | Flow blocked The WhatsApp Flow is in a blocked state. | Fix the Flow. |
| 132069 | Other | Flow throttled The Flow is throttled and already sent 10 messages in the last hour. | Fix the Flow errors. |
| 133000 | Other | Previous deregistration failed An earlier deregistration didn’t complete. | Deregister again before registering. |
| 133004 | Other | Server temporarily unavailable The server is briefly unavailable. | Check the status page and the error details, then retry. |
| 133005 | Other | Two-step PIN incorrect The two-step verification PIN is wrong. | Use the correct PIN, or disable and set a new PIN. |
| 133006 | Other | Number needs verification The phone number must be verified before registering. | Verify and then register the number. |
| 133008 | Other | Too many PIN guesses Too many wrong two-step PIN attempts. | Wait for the time shown in the error details. |
| 133009 | Other | PIN entered too fast PIN attempts were too quick. | Check the error details and wait before retrying. |
| 133010 | Other | Number not registered The number isn’t registered on the WhatsApp Business Platform. | Register it before sending. |
| 133015 | Other | Number recently deleted Deletion of this number hasn’t finished. | Wait about 5 minutes, then retry. |
| 134011 | Other | Payments terms not accepted WhatsApp Payments terms of service are pending. | Accept the terms using the link in the error message. |
| 135000 | Other | Unknown request parameter error Something is wrong with the request parameters. | Check the endpoint syntax and contact support if it continues. |
| 100 (MM API) | Marketing Messages API | Must be a template message You sent a non-template message on the Marketing Messages API. | Send a marketing template. |
| 131009 (MM API) | Marketing Messages API | Parameter value not valid An invalid parameter, or ad syncing isn’t complete. | Check parameters, wait 10 minutes and retry. |
| 131055 | Marketing Messages API | Method not allowed Only marketing templates are supported on this API. | Send a marketing template message. |
| 134100 | Marketing Messages API | Only marketing messages supported You tried to send a utility or authentication template. | Use a template categorised as Marketing. |
| 134101 | Marketing Messages API | Template still syncing A new template can take up to 10 minutes to sync. | Wait 10 minutes and try again. |
| 134102 | Marketing Messages API | Template unavailable Ad sync failed, or you may not be eligible for the API. | Check your onboarding status and contact Meta support if needed. |
| 132018 | Marketing Messages API | Template validation error There’s a problem with the template’s parameters. | Fix the parameters and resend. |
| 1752041 | Marketing Messages API | Duplicate request The business was already invited to onboard by another partner. | No action needed – eligible accounts are onboarded automatically. |
Explained in simple words from Meta’s WhatsApp error codes documentation (updated June 2026). Meta may add or change codes – always check the latest official documentation.
Frequently Asked Questions
More than 24 hours passed since the customer last replied. Send an approved template message to restart the conversation.
The message could not be delivered – the number may not be on WhatsApp, may use an old app version, or may have blocked you.
Send exactly the same number of variables as your template has.
Your access token has expired or is invalid. Create a new token – use a permanent system-user token for production.
Too many earlier messages were blocked or reported. Check your quality rating and message only opted-in customers.
Failed messages and their reasons appear in your WATick panel and in webhook events.
Tired of Debugging WhatsApp API Errors?
WATick handles the technical side – you focus on your customers.