> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useinvent.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp error codes
> Every WhatsApp Cloud API error code explained in plain language, with what it means and how to fix it. Covers send failures, rate limits, template rejections, the 130497 country restriction, and more.
When a WhatsApp message, template, or broadcast fails, Meta returns a numeric **error code**. The same codes show up across the whole WhatsApp Business Platform, so they look identical whether the message was sent by Invent, by another tool, or directly through Meta's Cloud API. This page explains what each code means and what to do about it, framed for what you actually see inside Invent.
You almost never need to handle these codes by hand. Invent surfaces the failure reason on the affected chat or broadcast recipient. This page is for understanding *why* a send failed and what to change so the next one succeeds.
## How WhatsApp reports errors
Meta's Cloud API is built on the Graph API, so every error follows the same shape:
```json theme={"system"}
{
"error": {
"message": "(#130429) Rate limit hit",
"type": "OAuthException",
"code": 130429,
"error_data": {
"messaging_product": "whatsapp",
"details": "Cloud API message throughput has been reached."
},
"fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
}
}
```
A few things worth knowing:
* **The `code` is what matters.** Build your understanding around the numeric `code` and the `details` text. The human-readable title inside `message` (for example *Rate limit hit*) is informational and Meta plans to deprecate titles eventually.
* **Errors arrive two ways.** Some come back immediately as the API response when a send is rejected outright. Others arrive later through a webhook, when a message was accepted but then failed to deliver (the recipient blocked you, their number is not on WhatsApp, and so on). Invent listens to both and attaches the reason to the chat or broadcast recipient.
* **`fbtrace_id` is your support ticket key.** If you ever escalate to Meta Direct Support, include this value. It lets them find the exact request.
## Codes you'll most likely see
These are the handful that come up in normal day-to-day use of WhatsApp in Invent.
A Meta-side restriction on **cross-country messaging**, not a problem with your connection. Business-initiated messages that cross a border into **Brazil (BR)** or **Indonesia (ID)** are blocked. Same-country messaging (Brazil to Brazil, Indonesia to Indonesia) still works, and **inbound messages are never affected**. The only reliable way to message users inside those countries is a WhatsApp Business account whose business is registered locally there. Full table and details in the channel guide: [Business account is restricted from messaging users in this country](/assistants/channels/whatsapp#troubleshooting).
WhatsApp only lets you send free-form messages inside a **24-hour customer service window** that opens each time the user messages you. Once 24 hours pass with no reply from them, free-form text is blocked and you must use an **approved template message** to re-open the conversation. In Invent this is the most common reason an assistant reply silently fails on an older chat. Send a template, or wait for the user to message again.
The message could not be delivered. Common reasons: the recipient's number is **not a WhatsApp number**, they have not accepted WhatsApp's latest Terms of Service, or they are on a very old WhatsApp version. Confirm the number is correct and actually on WhatsApp. There is nothing to fix on your side if the recipient simply does not use WhatsApp.
This user chose to stop receiving **marketing** template messages from your business on WhatsApp. **Do not retry**, the message will never be delivered. You can still send utility and authentication templates, and you can still reply inside the 24-hour window. Respect the opt-out.
Meta throttled a marketing template to this specific user to protect engagement quality (the per-user marketing limit). Wait at least 24 hours before resending. Retrying sooner just produces the same error.
You sent too many messages from your number to the **same** recipient in a short window. Wait and retry for that contact. You can keep messaging *other* numbers normally, so this rarely affects a broadcast as a whole.
The template name or language locale is wrong, or the template has not been approved yet. Check the exact template name and language in WhatsApp Manager, and confirm its status is **Approved** before sending. Newly created templates can take a few minutes to become sendable.
The template was rejected on review for a policy reason. Read Meta's template review guidance, edit the content to comply, and resubmit. Until it is approved again it cannot be sent.
`132015` means the template was **paused** because recipients reacted poorly (blocks, reports, low read rates). Improve the content and it can be re-enabled once approved. `132016` means it was paused too many times and is now **permanently disabled**. Create a fresh template with better content.
These all mean *slow down or improve quality*, but for different reasons:
* **80007**: your WhatsApp Business account hit its messaging rate limit. Retry later or send less frequently.
* **130429**: Cloud API throughput limit reached. Same fix: spread sends out over time.
* **131048**: sends are restricted because too many earlier messages were blocked or flagged as spam. Check your quality rating in WhatsApp Manager.
* **131064**: messaging limit reached due to template classification violations. Make sure your templates are categorized correctly (marketing vs utility vs authentication).
**190** means the access token behind the connection has expired. In Invent, reconnect the WhatsApp connection from [Settings → Connections](/workspace-management/connections) to refresh it. **368** means the whole WhatsApp Business Account has been **restricted or disabled for a policy violation**. This is serious: review Meta's Policy Enforcement page and resolve the violation in WhatsApp Manager. No message will send until the account is reinstated.
Something is wrong with billing on the WhatsApp Business account: no payment method attached, credit line over its limit or inactive, currency or timezone not set, or the account is suspended. Fix billing in WhatsApp Manager and try again.
Your business blocked this WhatsApp user, so the message cannot be delivered. **Do not retry.** Unblock them first if you want to resume messaging.
## Full error code reference
Every code from Meta's [Cloud API error reference](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/), grouped the way Meta groups them. The common ones above are repeated here for completeness.
### Authorization errors
These mean the request was not allowed to run at all, usually a token or permission problem. In Invent the fix is almost always to **reconnect** the WhatsApp connection.
| Code | What it means | What to do |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `0` | Could not authenticate the app user. The access token expired, was invalidated, or a setting blocks access. | Reconnect WhatsApp to get a fresh token. |
| `3` | A capability or permission is missing for this request. | Confirm the connection was authorized with all required permissions; reconnect if needed. |
| `10` | A required permission was never granted or has been removed. | Re-run the connect flow and grant all requested permissions. Check you are eligible for the endpoint being used. |
| `190` | The access token has expired. | Reconnect WhatsApp from [Settings → Connections](/workspace-management/connections). |
| `200` | No access token was provided on a request that requires one. | Reconnect WhatsApp. (Distinct from `190`, which is an expired token.) |
| `200`–`299` | A permission is not granted or was removed. | Re-authorize the connection with the required permissions. |
### Integrity errors
Account-level enforcement. These block sending until the underlying issue is resolved with Meta.
| Code | What it means | What to do |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `368` | The WhatsApp Business Account was restricted or disabled for violating a platform policy. | Review Meta's Policy Enforcement page, resolve the violation in WhatsApp Manager. |
| `130497` | The account is restricted from messaging users in certain countries (the Brazil / Indonesia cross-country restriction). | See [the full explanation and country table](/assistants/channels/whatsapp#troubleshooting). No override; use a locally-registered account to reach those users. |
| `131031` | The account was restricted or disabled for a policy violation, or request data (such as the two-step PIN) could not be verified. | Check Policy Enforcement and the Health Status API. Verify any PIN or credentials in the request. |
### Throttling and rate limits
Everything here means *send slower or improve quality*. None require a structural fix, only pacing.
| Code | What it means | What to do |
| -------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `4` | The app hit its overall API call rate limit. | Retry later or reduce request frequency. |
| `80007` | The WhatsApp Business Account hit its rate limit. | Retry later or send less frequently. |
| `130429` | Cloud API message throughput limit reached. | Spread sends out over time. |
| `131048` | Sends are restricted because too many earlier messages were blocked or flagged as spam. | Check quality status in WhatsApp Manager; improve template quality. |
| `131056` | Too many messages to the **same** recipient in a short period. | Wait and retry that contact; other numbers are unaffected. |
| `131064` | Messaging limit reached due to template classification violations. | Ensure templates are categorized correctly; the limit lifts after the enforcement period. |
| `133016` | Too many register / deregister attempts for this number in a short period. | Wait until the number is unblocked, then retry. |
### Sending and delivery errors
The most common day-to-day failures when a specific message cannot be delivered.
| Code | What it means | What to do |
| -------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `130403` | You blocked this user, so the message cannot be delivered. | Do not retry; unblock the user to resume. |
| `130472` | Message was not sent as part of a marketing experiment. | Expected for the Marketing Message Experiment; no action. |
| `131021` | Sender and recipient phone numbers are the same. | Send to a number different from the sender. |
| `131026` | Undeliverable: recipient is not on WhatsApp, has not accepted the latest Terms, or is on a very old app version. | Confirm the number is correct and on WhatsApp; nothing to fix if they do not use WhatsApp. |
| `131045` | Send failed due to a phone number registration error. | Ensure the number is registered before sending. |
| `131047` | More than 24 hours since the recipient last replied. | Send an approved template to re-open the conversation. |
| `131049` | Held back to maintain healthy ecosystem engagement (per-user marketing limit). | Wait at least 24 hours before resending. |
| `131050` | Recipient opted out of marketing messages from your business. | Do not retry; you may still send utility / authentication templates. |
| `131051` | Unsupported message type. | Use a supported message type. |
| `131052` | Could not download media the user sent. | Ask the user to resend the file by another method; check `error_data.details`. |
| `131053` | Could not upload the media in your message (often an unsupported type). | Verify the file's MIME type is supported; inspect with `file -I`. |
| `131057` | The account is in maintenance mode (for example a throughput upgrade). | Wait and retry. |
| `131063` | Template is Marketing, but marketing templates are disabled for this Cloud API config. | Re-enable marketing on Cloud API, or use the Marketing Messages API. |
| `134011` | Send blocked: WhatsApp Payments Terms of Service acceptance is pending. | Accept the Payments ToS via the link in the error, then retry. |
### Template errors
Creating, sending, and quality issues with message templates.
| Code | What it means | What to do |
| --------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
| `2388040` | A template field exceeded its character limit. | Shorten the field named in the error. |
| `2388047` | Message header format is invalid. | Fix the header formatting per the error detail. |
| `2388072` | Message body format is invalid. | Fix the body formatting per the error detail. |
| `2388073` | Message footer format is invalid. | Fix the footer formatting per the error detail. |
| `2388293` | Too many variables for the template's length. | Reduce variables or lengthen the message. |
| `2388299` | A variable sits at the very start or end of the template. | Move variables away from the leading / trailing position. |
| `2388019` | Reached the maximum number of templates for this account. | A WABA allows up to 250 templates; delete unused ones. |
| `132000` | Variable count in the request did not match the template definition. | Send a value for every variable the template defines. |
| `132001` | Template does not exist in that language, or is not approved. | Check the name and locale; confirm the template is approved. |
| `132005` | Translated text is too long. | Shorten the translation; verify it in WhatsApp Manager. |
| `132007` | Template content violates a WhatsApp policy. | Edit to comply and resubmit for review. |
| `132012` | Variable values formatted incorrectly. | Match the format the template specifies. |
| `132015` | Template paused for low quality. | Improve the content; it can return once re-approved. |
| `132016` | Template permanently disabled after being paused too many times. | Create a new template with better content. |
| `132068` | Flow is in a blocked state. | Correct the Flow. |
| `132069` | Flow is throttled (10 messages already sent in the last hour). | Correct the Flow and wait. |
### Template insights errors
Niche; only relevant if you toggle template analytics directly.
| Code | What it means | What to do |
| -------- | ----------------------------------------------------- | ---------------------------------------------- |
| `200005` | Template insights not available yet for this account. | Cannot be enabled at the moment. |
| `200006` | Template insights cannot be disabled once enabled. | No action; this is by design. |
| `200007` | Template insights are not enabled for this account. | Enable them via Confirming template analytics. |
### Phone number registration and migration errors
These appear during number setup and migration between accounts, not during normal messaging.
| Code | What it means | What to do |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `33` | The business phone number has been deleted. | Verify the number is correct. |
| `133000` | A previous deregistration attempt failed. | Deregister the number again before registering. |
| `133004` | Server temporarily unavailable. | Check the Platform Status page and retry. |
| `133005` | Two-step verification PIN incorrect. | Verify the PIN; reset it by disabling and re-enabling two-step verification. |
| `133006` | Number must be verified before registering. | Verify and register the number. |
| `133008` | Too many two-step PIN guesses. | Wait the period stated in `details`. |
| `133009` | Two-step PIN entered too quickly. | Check `details` and slow down. |
| `133010` | Number is not registered on the platform. | Register the number first. |
| `133015` | The number was recently deleted and deletion has not finished. | Wait 5 minutes and retry. |
| `2388012` | The number already exists in your account. | Use a number not already present. |
| `2388091` / `2388093` | Number not eligible to receive / verify a registration code (not being migrated). | Register and verify the number normally. |
| `2388103` | A migration failure with several possible causes (webhooks not set up, display name not approved, no payment account, wrong Business Manager, account not approved, "Messaging For" not approved, or a generic error). | Read the `details` text; it names the exact cause and fix. Some cases require contacting Meta support. |
| `2494100` | The number is in maintenance mode. | Try again in a few minutes. |
### WhatsApp Business Account and ownership errors
Rare; tied to the deprecated On-Behalf-Of (OBO) ownership model.
| Code | What it means | What to do |
| --------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `2593079` | WABA already marked for migration to a different solution ID. | OBO is deprecated; contact Meta support. |
| `2593085` | WABA not eligible for OBO ownership transfer (already owned, or the request was not accepted). | OBO is deprecated; contact Meta support. |
### Onboarding synchronization errors
Only relevant during Coexistence onboarding, when contacts and history sync.
| Code | What it means | What to do |
| --------- | --------------------------------------------------------------------- | ---------------------------------------------- |
| `2593107` | Exceeded the allowed number of synchronization calls for this number. | Offboard and re-onboard the business customer. |
| `2593108` | Synchronization can only run within 24 hours of onboarding. | Offboard and re-onboard the user. |
### General and server errors
Catch-alls for malformed requests and platform outages.
| Code | What it means | What to do |
| -------- | ------------------------------------------------- | ---------------------------------------------------------- |
| `1` | Invalid request or possible server error. | Check the Platform Status page; verify request formatting. |
| `2` | Temporary issue from downtime or overload. | Check Platform Status before retrying. |
| `100` | One or more unsupported or misspelled parameters. | Check parameter names, values, and length limits. |
| `131000` | Unknown error. | Retry; if it persists, open a Meta Direct Support ticket. |
| `131005` | Permission not granted or removed. | Re-authorize the connection. |
| `131008` | A required parameter is missing. | Add the required parameter. |
| `131009` | One or more parameter values are invalid. | Use supported values for each parameter. |
| `131016` | A service is temporarily unavailable. | Check Platform Status and retry. |
| `131037` | The sending number has no approved display name. | Get the display name approved in WhatsApp Manager. |
| `135000` | Unknown error with your request parameters. | Verify request syntax; contact support if it persists. |
### Marketing Messages API errors
Only relevant if you use Meta's Marketing Messages (MM) API, which reuses Cloud API codes plus these additions.
| Code | What it means | What to do |
| --------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `100` | The message must be a template message. | Send a marketing **template**, not a free-form message. |
| `131009` | Parameter value is not valid (or ad sync incomplete). | Verify parameters; if ad syncing, wait 10 minutes and retry. |
| `131055` | Only marketing template messages are supported here. | Send a marketing template, not utility / authentication or free-form. |
| `134100` | Only marketing messages are supported on this API. | Use a template categorized as Marketing. |
| `134101` | Your template is still syncing (up to 10 minutes after creation). | Wait a few minutes and resend. |
| `134102` | Template unavailable; ad sync failed or you are not onboarded. | Check eligibility; if `marketing_messages_lite_api_status` is `ONBOARDED` and it persists, contact support. |
| `132018` | Template validation error in the parameters. | Fix the parameters and resend. |
| `1752041` | Duplicate onboarding request; the client was already invited by a partner. | No action; all eligible WABAs onboard automatically. |
## Still stuck?
* For send failures, the fastest signal is usually your **quality rating and messaging limits** in [WhatsApp Manager](https://business.facebook.com/wa/manage/).
* For account-level restrictions (`368`, `130497`, `131031`), the resolution lives with Meta, not inside Invent.
* When escalating to Meta, include the `fbtrace_id` from the error so Direct Support can trace the exact request.
* For connection or token issues (`0`, `190`, `200`, `131005`), reconnect WhatsApp from [Settings → Connections](/workspace-management/connections).