A WhatsApp Business API error comes back with a numeric code, a short message and a trace ID. The code tells you which kind of problem you have: a message that could not be delivered, a template that does not match, a permission that is missing, a rate limit, or a restriction on the account. This page is the index: what each common code means, whether retrying helps, and which guide covers the fix.
It is written for two readers. If your business runs WhatsApp through a provider, you usually see the error in the provider's inbox or send log, and most fixes happen in Meta's WhatsApp Manager or Business Suite, or by reconnecting the account. If you build on the Cloud API yourself, the same codes come back in the API response or on the status webhook. Codes and meanings are checked against Meta's error code reference as of November 3, 2026.
How to read a WhatsApp error
code: the number to act on. Meta no longer returns error subcodes, so build handling around the code and the details text.
message: the code and a title together, such as "(#130429) Rate limit hit".
details: a description of the cause, often more specific than the title. Read it first.
fbtrace_id: the trace ID Meta support asks for. Keep it with the timestamp.
Some errors come back on the send request itself. Others come later, when the API has accepted the message but WhatsApp could not deliver it, and arrive as a failed status on your webhook. A message that "sent" in your system can still have failed.
Quick index of WhatsApp Business API errors
Delivery errors
| Code | What it means | What to do |
|---|---|---|
| 131026 | Message undeliverable. The recipient may not have WhatsApp, may not have accepted the latest terms of service, or may be on an old WhatsApp version. | Do not retry the same send. Work through the causes in error 131026: message undeliverable. |
| 131047 | Re-engagement message. More than 24 hours have passed since the customer last replied. | Send an approved template. See the 24 hour messaging rule. |
| 131049 | Meta chose not to deliver a marketing template, to keep engagement healthy for that user. | Wait at least 24 hours before sending the same marketing template to that person again. See error 131049: healthy ecosystem engagement. |
| 131050 | The customer has stopped marketing messages from your business. | Do not retry. Respect the opt-out. |
| 131060 | Seen on numbers in coexistence (the WhatsApp Business app and the API on one number). Meta gives as one reason a customer with an unsupported companion device sending or receiving the message. | See error 131060: companion device. |
| 131042 | Payment method error. No valid payment method on the account, a credit line over its limit, or a suspended account. | Fix billing in Meta Business Suite before sending again. See error 131042: payment issue. |
| 131052, 131053 | Media could not be downloaded (131052) or uploaded (131053), usually an unsupported file type. | Check the file type against Meta's supported media list and the details text. See error 131052: media download error. |
Template errors
| Code | What it means | What to do |
|---|---|---|
| 132001 | The template does not exist in that name and language, or is not approved. Often shown as "Template name not found". | Check the exact name and language code, and that the template is approved. See template name not found. |
| 132000 | The number of variable values sent does not match the template. | Send a value for every variable. |
| 132012 | A variable value is in the wrong format. | Match the format the template expects. |
| 132005 | The text with variables filled in is too long. | Shorten the variable values. |
| 132007 | The template content breaks a WhatsApp policy. | Rewrite it. See WhatsApp template rejected? Here's how to fix it. |
| 132015 | The template is paused because of low quality. | Edit it to improve quality, or send a different template. |
| 132016 | The template has been paused too many times and is now permanently disabled. | Create a new template with different content. |
How to write templates that avoid these errors is in the WhatsApp template guide.
Permission and access token errors
| Code | What it means | What to do |
|---|---|---|
| 190 | The access token has expired or is invalid. "Error validating access token: Session has expired" is this error. | Get a new token. On a provider, reconnect the WhatsApp account. See session has expired. |
| 0 | Meta could not authenticate the app user. | Get a new access token. |
| 3 | The app lacks a capability or permission for this call, for example "Application does not have the API granular permission". | Reconnect and grant every permission requested. See error #3: API granular permission. |
| 10, 131005 | A permission was not granted or has been removed. | Check the token's permissions in Meta's access token debugger, then reconnect. |
| 200 to 299 | No token, or the token lacks permission, for example "You do not have the necessary permissions required to send messages on behalf of this WhatsApp Business Account". | Check who owns the WhatsApp Business account and that the app is linked to it. See error #200: no permission to send. |
| 100 | Invalid parameter: misspelled, unsupported or with a value the endpoint does not take. "Object with ID does not exist, cannot be loaded due to missing permissions" also returns this code. | Check the request against Meta's reference. For the missing object message, see object does not exist. |
A connection can also stop because Meta wants the admin to log in to Facebook and pass a check first. That case is covered in you cannot access the app till you log in to Facebook.
Rate limit errors
| Code | What it means | What to do |
|---|---|---|
| 130429 | The phone number's message throughput limit has been reached. | Queue messages and retry with a growing wait. |
| 131056 | Too many messages to the same recipient in a short time. | Wait before sending to that number again. |
| 131048 | Sending restricted because too many messages were flagged as spam. | Check the number's quality in WhatsApp Manager and slow down. |
| 4 | The app has made too many API calls. | Wait and reduce how often you call. |
| 80007 | The WhatsApp Business account has made too many API calls. | Reduce how often you call for that account. |
| 131064 | The account hit its messaging limit because of template category violations. | Review how templates are categorized. The restriction lifts on its own. |
The daily cap on how many people you can start conversations with is a separate limit, explained in WhatsApp messaging limits.
Account and compliance problems
| Error | What it means | Guide |
|---|---|---|
| 368, 131031 | The account is restricted or locked, usually for a policy violation. 131031 can also mean a wrong two-step verification PIN. | Restore a blocked WhatsApp account |
| "This account can no longer use WhatsApp" | The number has been banned. | Appeal guide |
| 459 | Meta has put the admin's Facebook account through a security checkpoint. It comes from the Facebook login, so it is not on the WhatsApp error list. | How to fix Meta error 459 |
Setup and onboarding problems
| Error | What it means | Guide |
|---|---|---|
| "This phone number is already registered with the INBOX product" | Another provider still holds the number. | Number already registered |
| "Your phone number is not eligible to connect to the WhatsApp Business Platform" | Meta will not yet onboard this number. | Phone number not eligible |
| Cannot remove the WhatsApp Business app from a Meta portfolio | Usually blocked by two-factor settings in Meta Business Suite. | Unable to remove from Meta portfolio |
| "Need to add payment method first" before a broadcast | No payment method on the Meta business portfolio. | Add a payment method |
| 133010 | The phone number is not registered on the Cloud API. | Complete registration before sending. |
A troubleshooting workflow that prevents repeat failures
Capture the exact error. Note the code, the details text, the fbtrace_id and the time. In a provider's inbox, the failed message usually shows the code.
Classify it with the tables above: delivery, template, permission, rate limit, account or setup.
Check the account state in Meta. Billing, business verification, the token's permissions, the number's status and quality, and the template's status in WhatsApp Manager.
Fix the cause, then send once. Repeating a send that fails for a fixed reason does not help and can hurt your quality signals or keep a rate limit in place.
Escalate with context. Give your provider or Meta support the code, the fbtrace_id, the time window and what you already tried.
When retrying helps
Retry rate limit errors (4, 80007, 130429, 131056) and temporary errors such as 131000 (unknown send error) and 131016 (service temporarily unavailable), with exponential backoff: wait 1 second, then 2, 4, 8, up to a cap, with a little random jitter. Before retrying 131016, check the WhatsApp Business API status page. Do not retry 131026, 131047, 131050, 131042 or template errors unchanged.
When delivery updates and replies stop arriving
Delivery statuses and customer replies reach your system through a webhook. If they stop, there may be no error code at all. Check that the callback URL is public, served over HTTPS with a valid certificate, set correctly in your Meta app, and that your server answers each POST with 200 OK. Your server logs show whether requests are arriving. On a provider, this is the provider's side to check, so report it to them with the time it started.
How Volty helps
Volty runs on Meta's Cloud API for your business, so the same codes apply. Volty tracks the 24 hour window on each conversation and switches the composer to an approved template once the window closes, so a reply does not fail at the point of send with error 131047. When you hit an error, talk to Volty with the code and the time it happened.
Frequently asked questions
What does error code 100 mean in the WhatsApp Business API?
Code 100 means the request carried an invalid parameter: a parameter that is misspelled, not supported by that endpoint, or has a value the endpoint does not accept. It is not an authentication error. Check the request against Meta's reference for the endpoint. The message "Object with ID does not exist, cannot be loaded due to missing permissions" also comes back as code 100 and usually means the connection to the WhatsApp account needs to be authorized again.
How do I check whether my WhatsApp access token is still valid?
Paste the token into Meta's access token debugger, which shows whether it is valid, when it expires and which permissions it holds. An expired token returns error 190, and a token missing a permission returns code 3, 10 or a code from 200 to 299. If you use a provider, reconnecting the WhatsApp account in the provider's settings issues a new token.
Should I retry a WhatsApp message that failed?
Retry only rate limit errors (4, 80007, 130429, 131056) and temporary errors such as 131000 and 131016, with a growing wait between attempts. Do not retry 131026, 131047, 131050, 131042 or any template error unchanged, because the same message fails the same way. Fix the cause first: send a template, fix billing, or correct the template.
Why do I get error 131047 when replying to a customer?
Error 131047 means more than 24 hours have passed since the customer last messaged you, so the customer service window is closed and a free-form reply cannot be sent. Send an approved template instead. When the customer replies, a new 24 hour window opens.
Why are my messages accepted by the API but never delivered?
The API accepts a send before WhatsApp tries to deliver it, and a later failure arrives as a failed status on your webhook with its own error code, often 131026, 131049 or 131050. Check the status webhook for the message rather than the send response. If no status arrives at all, check that your webhook endpoint is reachable and answering.
What is exponential backoff?
Exponential backoff is a retry pattern where the wait between attempts grows each time, for example 1, 2, 4 and 8 seconds, with a cap. It spreads retries out so a rate limit can clear instead of being hit again straight away.










