WhatsApp API Error Codes Explained: 131031, 131047, 130429 and What to Do
A guide to the most common WhatsApp API error codes (131031 account locked, 131047 24-hour window, 130429 rate limit, 131049) and how to fix each one.
In this article
A message shows as sent, then a minute later flips to failed with a number next to it. If you run a business on the WhatsApp Business Platform, you will meet WhatsApp API error codes sooner or later, and the difference between a five-minute fix and a lost afternoon is knowing what each one means and where it came from.
This guide covers the codes behind most support tickets, with the meaning, the usual cause and what to do for each. It also explains something people miss in practice: some codes never appear in the response to your send request. They arrive later, in the status webhook, which is why a message can look successful and then fail. If you run the channel rather than the code, a good platform surfaces the code next to the message; you still need to know what it is asking you to do.
The codes at a glance
| Code | Meaning | Usual cause | What to do |
|---|---|---|---|
| 131031 | Business account locked | Unverified portfolio, failed payment, policy violation | Fix in Meta Business Manager |
| 131047 | Re-engagement message | Free text sent more than 24 hours after the customer's last message | Send an approved template |
| 130429 | Rate limit hit | Too many requests, or above your messaging tier | Slow down, queue sends, check the tier |
| 131049 | Marketing message not delivered ("healthy ecosystem") | Meta capped the marketing messages that user receives | Retry days later; prefer utility content |
| 131026 | Message undeliverable | No WhatsApp, user blocked you, or invalid number | Verify the number; if blocked, stop messaging that contact |
| 131048 | Spam rate limit hit | Quality dropped, too many messages flagged | Pause campaigns, review quality |
| 131056 | Pair rate limit hit | Too many messages to the same recipient quickly | Space out messages to that contact |
| 190 | Access token expired or invalid | Token revoked, password changed | Reconnect the channel |
| 131009 | Parameter value not valid | Variables do not match the approved template | Fix the variable count or format |
| 141006 | Payment method issue | No valid card on the account | Add or update the company card |
| 141010 | Business not verified | Verification never completed | Complete verification |
131031: business account locked, and why it looks like a platform bug
Error 131031 is the code behind the ticket "my channel is connected but nothing goes out". The account is locked by Meta, for one of three reasons: the business portfolio is new and unverified (a channel created inside a fresh portfolio can be locked from the first minute), a payment method failed, or a policy issue put the account under review.
The part that confuses people: 131031 usually does not come back in the response to your send request. The API accepts the message, returns an ID, and the platform marks it as sent. Then the delivery status webhook arrives with status: failed and the 131031 error object inside it. From the user's side, the message flips from sent to failed for no visible reason.
Two consequences. First, the truth about the account is in its health status, which Meta exposes and platforms show as the channel's state; if it says locked or restricted, stop debugging messages. Second, the fix is always in Meta Business Manager: verification, the card, or the policy notice. Preparing those in advance is the subject of the WhatsApp API checklist before you connect your number.
131047: outside the 24-hour window
Error 131047 means you sent a free-form message to a customer who has not written to you in the last 24 hours. WhatsApp only allows free text inside that window; outside it, the business must use an approved template. It is not a restriction on your account; it is the rule that keeps the channel from turning into email spam. Create templates for the situations where you reach out first (quote follow-up, appointment reminder, order update) and use them when the window is closed. A good shared inbox tells the agent the window has expired and offers the template. A re-engagement template that gets approved and gets replies:
Hi {{1}}, it's Priya from Redwood Kitchens. You asked for a quote on {{2}} last week.
Would you like me to book a 15-minute call to walk through it? Reply YES and I'll send times.
130429, 131048, 131056 and 131049: the limits
The first three are often lumped together as "rate limit" but mean different things.
- 130429 is the throughput limit: too many API calls too fast, or more business-initiated conversations than your messaging tier allows in 24 hours (250, 1,000, 10,000, 100,000 or unlimited). Queue sends and, if you keep hitting it, grow the tier through volume and quality.
- 131048 is the spam rate limit, tied to quality: Meta has flagged your number for too many unwanted messages and is throttling you. Pause campaigns, check the quality rating, see which templates are being reported. Ignore it and the next step is a lower tier or a restriction.
- 131056 is the per-pair limit: too many messages to one recipient in a short window, usually a bot loop or an automation firing twice for the same event.
131049 is different: a per-user marketing cap. Meta limits how many marketing template messages a given WhatsApp user receives in a period, across all businesses. If that user already received several recently, your marketing template is not delivered and you get 131049 with a "healthy ecosystem" explanation. Your number did nothing wrong; the cap is on the recipient. Retry days later, and consider whether the message should be a utility template (order update, booking confirmation), which is not subject to that cap. Planning around it is covered in how to plan campaigns around WhatsApp marketing message limits.
131026, 190 and 131009: contact, token and template problems
131026 means the message cannot reach that recipient: no WhatsApp account, the recipient blocked your business, or an invalid number. If a contact returns it repeatedly, remove them from campaigns; messaging a number that blocks you lowers your quality rating.
190 is an authentication error: the access token is expired, revoked or missing permissions, usually after a password change or a removed permission on the Meta account. Reconnect the channel from the platform to generate a fresh token; no message content is involved.
131009 is a template parameter error: too many or too few variables, a newline or emoji in a variable, or a media header sent to a text-only template. Compare what you send with the approved template in Meta's template manager.
A short triage procedure
When a message fails, work through this in order rather than guessing:
- Check the channel's health status. If the account is locked or restricted, that explains everything; go to Meta Business Manager.
- Look at the error code, not only at "failed".
- Did the customer write in the last 24 hours? If not and you sent free text, it is 131047.
- Is it a campaign? Rate limits (130429, 131048) and the per-user cap (131049) mostly appear during broadcasts.
- One contact or all of them? One points to 131026 or 131056; all point to 131031, 190 or a billing code.
- Only then look at the message content (131009 for templates).
Omnifox shows the code and its plain-language reason next to each failed message, alongside the channel's quality rating, phone status and messaging tier.
Frequently asked questions
Why does my message show as sent and then fail with 131031?
Because the API accepts the send request and only later reports, through the status webhook, that the business account is locked. The send response does not know about the lock; the account's health status does.
What is the difference between 131047 and 131049?
131047 means you sent free text outside the 24-hour window and need a template. 131049 means your marketing template was not delivered because Meta capped the marketing messages that user receives; retry later or use a utility template.
How do I fix error 190 on the WhatsApp API?
Reconnect the channel so the platform obtains a new access token. Error 190 is about authentication, not the message, and usually follows a password change or a removed permission.
Is error 130429 a sign my number is in trouble?
Not by itself. 130429 is a throughput or tier limit, not a quality judgment. If it comes with 131048 or a falling quality rating, slow down and review your campaigns.
Read the code, then fix the right thing
Account-level problems (131031, 141006, 141010, 190) affect every message and live in Meta Business Manager; window and template problems (131047, 131009) live in how you write; limits (130429, 131048, 131056, 131049) live in how much and to whom you send. A platform that shows the code, the reason and the channel's health in one place turns a confusing afternoon into a two-minute check. Try the official WhatsApp Business API with Omnifox on a 7-day free trial.
Ready to try it in your business?
Bring WhatsApp, Instagram, Messenger, email and calls into one inbox, and let AI handle the first reply. Set it up today.
7 days free. No credit card required.
Read more
-

After-Hours Auto-Reply: How to Stop Losing Customers at Night and on Weekends
-

WhatsApp CRM in Malaysia: 2026 Guide to Sell More
-

Contact Segmentation in Your CRM With Tags
-
Abandoned Cart Recovery for Canadian Online Stores
-

Follow-Up Tasks and Reminders in Your CRM
-

Signs Your WhatsApp Number Is About to Be Banned
-

Unified Customer History Across Every Channel
-

From First Contact to Close: The CRM Sales Flow
Comments (0)
No comments yet. Be the first to share your thoughts.
Leave a comment
Your email is never published. Comments are moderated before appearing.