Too Long? Read This First ● WhatsApp Business API errors usually fall into five types: account setup, templates, delivery, rate limits, or integration. Identify the type first, then check the code. ● Error 131047 means the 24-hour customer service window has closed. Send an approved template instead of a regular message. ● Template rejections often happen because the wrong category was selected. Marketing content submitted as Utility is likely to be rejected. ● A red quality rating does not cause an instant ban, but it can pause templates and block messaging limit upgrades. ● Errors 131048 and 130429 usually mean you are sending too quickly. Slow down, retry after a delay, and improve your opt-in list. |
Your Diwali campaign is scheduled. 40,000 contacts, template approved, everything queued.
You hit send and the dashboard fills with red. 131047. 132001. 131048.
No plain-English explanation, just a wall of five-digit codes and a campaign that isn't going out.
If you've run WhatsApp Business API, Meta's official channel for messaging customers at scale for more than a few weeks, you've met these codes. Since Meta controls the entire pipeline, every failure comes back as a number.
The channel is too valuable to lose a campaign over a code you don't recognise:
- 3 billion+ people on WhatsApp
- Open rates touching 98%
The good news: WhatsApp API errors are more predictable than they look.
- Nearly every error traces back to five root causes
- Most take under 10 minutes to fix once you know which bucket you're in
This guide covers every error code you're likely to hit, what actually causes it, and exactly how to fix it.
What Are WhatsApp Business API Errors?
A WhatsApp Business API error is a coded response Meta returns when a request you've made - sending a message, submitting a template, registering a number - can't be completed.
Unlike the WhatsApp Business App, where a failed message just shows a clock icon, the API tells you precisely what went wrong. That's a feature, not a bug. The problem is that Meta's error messages are written for developers, not marketers, so "Re-engagement message" doesn't obviously translate to "your 24-hour window expired."
Every error you'll encounter belongs to one of five buckets:
- Account & setup errors - your number, WABA, or business verification isn't in a state that allows sending
- Template errors - the template doesn't exist, was rejected, got paused, or your variables don't match
- Delivery errors - the message was valid but couldn't reach that specific recipient
- Rate limit errors - you're sending faster or more than your account is currently allowed
- Integration errors - your token, webhook, or connected tool broke the chain
Knowing the bucket usually gets you 80% of the way to the fix. The code gets you the rest.
How to Read a WhatsApp API Error Response
Every failed request returns a JSON object that looks roughly like this:
{
"error": {
"message": "(#131047) Re-engagement message",
"type": "OAuthException",
"code": 131047,
"error_data": {
"messaging_product": "whatsapp",
"details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number."
},
"fbtrace_id": "AbCdEfGhIjK"
}
}Four things matter here:
- code - The five-digit number. This is what you search for, and what everything below is organised by.
- message - Meta's short title. Often cryptic ("Re-engagement message" tells you almost nothing on its own).
- error_data.details - The actual explanation in plain English. Most people skip straight to the code and miss this field, which usually names the exact problem.
- fbtrace_id - A unique ID for that specific request. Always include this when you raise a support ticket; without it, Meta can't look up what happened.
Where to check errors:
- In AiSensy: Open the campaign and go to Delivery Logs. You’ll see the error code for each failed contact.
- In Meta: Open WhatsApp Manager to check template quality, account issues, or phone number restrictions.
Important Note* If the same error appears for everyone, the issue is likely to be related to the account or the template being sent.
If only some contacts are affected then it is likely to be a delivery issues.
Read More: How to Send Clickable Links on WhatsApp
WhatsApp Business API Error Codes - Full Reference Table
Here's the complete list of codes you're realistically going to encounter, grouped by type. Bookmark this section - it's the fastest way to go from a code to a cause.
Authorization & Permission Errors
These are token/credential errors that a BSP handles for the user - a marketer on your platform never touches them.
These errors are managed by your BSP (like AiSensy), so you better contact support in case you witness these errors.
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 0 | Unable to authenticate | Token expired, invalidated, or access revoked | Generate a new access token |
| 3 | Capability or permissions issue | Token lacks the required permission | Check permissions in Meta's Access Token Debugger |
| 10 | Permission denied | Permission was never granted or has been removed | Re-authorise the app in Business Manager |
| 190 | Access token expired | Your Meta authorisation lapsed | Reconnect via Embedded Signup |
| 200 | Authorization failure | Invalid token or missing permission scope | Reauthorise with the correct scopes |
| 131005 | Permission not granted | Token doesn't belong to this WABA or number | Confirm the token maps to the right business |
Throttling & Rate Limit Errors
This error means that you're sending too fast, or too much for your current tier.
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 4 | API rate limit reached | Your app hit its call rate ceiling | Back off, retry with exponential delay |
| 80007 | WABA rate limit | The WhatsApp Business Account hit its limit | Reduce request frequency |
| 130429 | Throughput limit | Cloud API message throughput exceeded (~80 msg/sec) | Queue messages and retry with backoff |
| 131048 | Spam rate limit | Too many of your recent messages were blocked or reported | Pause, clean your list, improve template quality |
| 131056 | Pair rate limit | Too many messages to the same recipient too quickly | Add per-recipient delay |
| 131064 | Classification limit | Messaging restricted due to template category violations | Re-check and correct template categories |
| 133016 | Too many registration attempts | Number registration retried excessively | Wait for the cooldown to lift |
Message Send & Delivery Errors
The request was valid, but the message couldn't reach that recipient.
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131026 | Message undeliverable | Recipient isn't on WhatsApp, has an outdated app, or can't receive it | Validate the number and opt-in status |
| 131047 | Re-engagement required | 24+ hours since the customer last replied | Send an approved template instead |
| 131049 | Marketing limit reached | Per-user marketing message cap hit | Wait 24 hours before resending |
| 131050 | Marketing opt-out | User has stopped marketing messages from you | Suppress from all marketing sends |
| 131051 | Unsupported message type | Message structure is wrong for the type declared | Fix the message object structure |
| 131052 | Media download failed | Couldn't download the user's media | Ask the user to resend |
| 131053 | Media upload failed | Your media couldn't be uploaded | Verify MIME type, size and URL |
| 130403 | User blocked by business | You've blocked this user | Unblock to resume sending |
Template Errors
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 132000 | Variable count mismatch | Number of variables sent ≠ number in the approved template | Match the variable count exactly |
| 132001 | Template not found | Template name or language doesn't exist / isn't approved | Check exact name, language code and approval status |
| 132005 | Translated text too long | Variable values pushed the template past its limit | Shorten your variable values |
| 132007 | Policy violation | Template content violates WhatsApp policy | Rewrite per Template Review guidelines |
| 132012 | Parameter format mismatch | Parameter values formatted incorrectly | Match component and button parameter formats |
| 132015 | Template paused | Low quality caused a temporary pause | Improve quality or switch templates |
| 132016 | Template disabled | Paused too many times, now permanently off | Create a new template with different content |
| 2388019 | Template limit exceeded | WABA is at its 250-template ceiling | Delete unused templates |
On the Cloud API - which virtually all businesses now use - their equivalents are 131047 and 131026 respectively.
Onboarding & Account Setup Errors
These block you before you've sent a single message. (If you haven't started your application yet, work through our step-by-step WhatsApp Business API application guide first - several of these errors only make sense in the context of where you are in that flow.)
"Number Already Registered" Error
This usually happens when the number is already active on WhatsApp or the WhatsApp Business App.
A phone number can only be connected to one WhatsApp product at a time, so you must remove or migrate it before registering it for the API.
Related codes you may see during this process:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 133000 | Deregistration incomplete | A previous deregistration didn't complete | Deregister again, then retry |
| 133010 | Number not registered | The number isn't registered on the platform yet | Complete registration before attempting to send |
| 133006 | Number not verified | The number hasn't been verified | Finish OTP verification first |
| 2388012 | Number already exists | The number already exists in the target WhatsApp account during a migration | Remove it from the target account, then retry the migration |
Important: if the number is on a physical SIM you still use for personal WhatsApp, don't do this.
Get a fresh number for the API. Once a number is on the API, you cannot use it in the WhatsApp app on your phone.
Business Verification and Display Name Rejection
These are two different checks when it comes to business verification and display name rejection issues.
Business Verification
Meta checks whether your business is legally registered. Verification may fail when your Business Manager details do not exactly match your documents.
For example, “Sharma Textiles Pvt. Ltd.” and “Sharma Textiles” may be treated as different names.
How to fix it:
- Match the legal business name exactly with your documents.
- Submit a document showing the business name, address, and registration number.
- Make sure your website shows the same business details.
- If rejected twice, contact Meta Support instead of uploading the same document again.
Display Name Rejection
The display name is the name customers see on WhatsApp.
Meta may reject names that:
- Do not match your business or brand
- Are too generic, such as “Best Deals”
- Include URLs, phone numbers, emojis, or offers
- Use a trademark you cannot prove you own
The safest option is your registered business name or a brand name clearly connected to your website.
Related error:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131037 | Display name not approved | Your test number doesn't have an approved display name yet | Submit a compliant display name and wait for approval before sending |
WhatsApp Message Template Errors
Template errors can block an entire campaign, making them one of the most common WhatsApp API issues.
Why Meta Rejects Templates
Most template rejections happen because the wrong category was selected.
Any message with promotional content is treated as Marketing. For example, a delivery update promoting new products may be rejected if submitted as Utility.
Here are the most common reasons templates get rejected:
| Rejection Reason | What Triggers It | How to Fix |
|---|---|---|
| Incorrect category | Promotional content submitted as UTILITY or AUTHENTICATION | Resubmit under MARKETING; keep utility templates purely transactional |
| Variable parameter issues | Template starts or ends with {{1}}, or has two variables adjacent | Always wrap variables in static text - Hi {{1}}, your order is confirmed |
| Too many variables for the length | Variable-to-text ratio too high | Add more static copy, or reduce variable count |
| Placeholder content | Sample values left as {{1}} or "lorem ipsum" | Provide realistic sample values for every variable |
| Policy violation (132007) | Prohibited industry, misleading claims, or restricted goods | Rewrite to remove the prohibited element; check Meta's Commerce Policy |
| Formatting errors (2388040, 2388047, 2388072) | Field exceeds character limit, or header/body/footer malformed | Body max 1,024 characters, header 60, footer 60 |
| Abusive or threatening tone | Aggressive debt-collection or pressure language | Neutral, factual phrasing |
| Broken link or mismatched URL | URL in the button doesn't resolve, or doesn't match your business | Use live URLs on your verified domain |
Three practical tips that dramatically improve approval rates:
- Do not start a message with a variable. Write “Hi {{1}}” instead of starting directly with “{{1}}”.
- Add proper sample values. Meta reviews the final message preview, not just the template format.
- Submit templates early. During busy periods, approval can take longer, so submit them at least 48 hours before your campaign.
Templates Paused, Disabled or Flagged
An approved template isn't approved forever. Meta continuously scores each template on how recipients respond to it.
132015 - Template paused. Your template's quality dropped to low, usually because of block and report rates. The pause is temporary:
- First pause: 3 hours
- Second pause: 6 hours
- Third pause: 24 hours
Paused templates resume automatically. Use the pause period to improve list quality and reduce sending frequency.
Error 132016 means the template is permanently disabled. Create a new template with different content.
To avoid this:
- Message only recent opt-ins
- Limit marketing frequency
- Segment your audience
- Monitor template quality weekly
Quick Template Fixes
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 132000 | Variable count mismatch | You sent 3 variables to a template expecting 2 (or vice versa) | Count them again, including button and header variables |
| 132001 | Template not found | Usually the language code - a template approved as en_US won't send if you call en | Check the exact language code, not just the name |
| 132005 | Translated text too long | Variable values pushed the rendered message past the character limit | Truncate long values (product names, addresses) before injecting them |
| 132012 | Parameter format mismatch | Component or button parameters don't match the approved structure - commonly a URL button variable passed in the body array | Match parameters to the approved component structure |
| 2388293 | Parameter ratio exceeds limit | Too many variables relative to static text | Add copy or cut variables |
| 2388019 | Template limit exceeded | You're at the 250-template ceiling | Delete unused templates |
WhatsApp Message Delivery Errors
These fire when the message itself is fine but the recipient or context isn't.
Error 131047 - Re-engagement Message Required
Error 131047 means the 24-hour customer service window has closed.
The window starts when a customer messages you. During those 24 hours, you can send regular replies, images, or documents.
Once the window closes, only approved template messages can be sent.
How to fix it:
- Check when the customer last messaged you
- If the window is closed, send an approved template
- Once the customer replies, the 24-hour window opens again
How to avoid it:
- Check the window timer before replying
- Create templates for time-sensitive follow-ups
- Use automated reminders before the window closes
Related errors:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131049 | Marketing limit reached | The user has hit Meta's per-user marketing message cap for that time window | Wait 24 hours before resending; segment to engaged users and space out marketing sends |
| 131050 | Marketing opt-out | The user has opted out of marketing messages from you | Suppress from all marketing sends until they opt back in on their device |
Error 131026: Message Undeliverable
This means WhatsApp accepted the message but could not deliver it. WhatsApp Message not Delivered, Fix it Now
Common reasons include:
- The number is not active on WhatsApp
- The country code or number format is incorrect
- The recipient is using an outdated WhatsApp version
- Their device does not support the message type
- The account is restricted
- Messaging is limited in that region
How to fix it:
- Use full international format without [+], spaces, or leading zeroes
- Validate numbers before uploading a contact list
- Remove numbers that repeatedly fail
- If many contacts show this error, check your list formatting first
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131051 | Unsupported message type | Your message object doesn't match the type you declared - usually a malformed interactive or media payload | Fix the message object structure to match the declared type |
| 130403 | User blocked by business | You blocked them at some point | Unblock in Live Chat to resume |
| 131031 | Account locked | Account-level restriction or a failed verification check | Check account health before retrying anything |
Rate Limit & Messaging Limit Errors
These are throttles, not penalties. They exist to stop a compromised or badly configured account flooding users.
WhatsApp Messaging Tiers Explained
Every WhatsApp Business Account sits in a messaging tier that caps how many unique customers you can start conversations with in a rolling 24 hours. Replies to customers who messaged you first don't count against it.
| Tier | Unique customers per 24 hours | How you get there |
|---|---|---|
| Tier 0 | 250 | Default for every new business portfolio |
| Tier 1 | 2,000 | Complete Business Verification, or send 2,000 quality messages to unique users in 30 days |
| Tier 2 | 10,000 | Automatic scaling |
| Tier 3 | 100,000 | Automatic scaling |
| Tier 4 | Unlimited | Automatic scaling |
Two important updates:
- Messaging limits now apply at the Business Portfolio level, so all connected numbers share the highest available tier.
- Meta reviews tier upgrades every few hours, so eligible accounts may upgrade on the same day.
How to Increase Your Messaging Limit
Meta usually upgrades your message limit when:
- You use at least 50% of your current limit within 7 days
- Your account and template quality remain high
Here is how to increase WhatsApp broadcast message limit
To improve your chances:
- Complete Business Verification
- Use your available limit consistently
- Keep your quality rating green
- Increase message volume gradually
- Maintain steady usage across the 7-day period
Rate Limit Error Codes
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131048 | Spam rate limit | The serious one - too many of your recent messages were blocked or reported, so Meta throttled you | Stop sending immediately, audit which template or segment drove the blocks, and resume at lower volume |
| 130429 | Cloud API throughput limit | You exceeded roughly 80 messages per second | Queue and retry with exponential backoff - any competent BSP handles this for you automatically |
| 4 / 80007 | API call rate limit | Your app or WABA is making too many API calls | Reduce polling frequency |
| 131056 | Pair rate limit | Too many messages to the same recipient too quickly | Add a per-recipient delay |
| 131064 | Classification limit | Restricted because of repeated template category violations | Audit your template categories |
| 132069 | Flow throttled | More than 10 flow messages sent in an hour to a recipient | Slow down |
Quality Rating & Account Restriction Errors
Quality rating is the metric that quietly determines everything else - your tier, whether templates stay live, and whether your number survives.
Green, Yellow & Red Quality Ratings Explained
Meta scores each phone number on how recipients react to your messages over a rolling 7-day window.
Blocks and reports drive it down; engagement and replies hold it up.
| Rating | What it means | What happens | What to do |
|---|---|---|---|
| Green (High) | Healthy engagement, minimal blocks | Full scaling eligibility | Maintain current practice |
| Yellow (Medium) | Blocks or reports rising | Tier upgrades freeze; you're being watched | Pause marketing, audit lists, cut frequency |
| Red (Low) | Significant negative feedback | Advancement blocked, templates start pausing | Stop all promotional sending for 7 days |
A red quality rating does not cause an instant downgrade, but if it continues, templates may be disabled and the number can be restricted.
Common causes include:
- Messaging users without clear opt-in
- Sending to old or inactive lists
- Sending promotions too frequently
- Broadcasting irrelevant messages
- Sending content users did not sign up for
Quality depends more on user reactions than message volume. Relevant messages to opted-in users can keep your rating healthy, while poor targeting can quickly turn it red.
What to Do If Your Number Is Restricted
Errors 368 or 131031 mean WhatsApp has stopped sending from your account. Here is how to unban your WhatsApp number
What to do:
- Check the restriction notice in Business Manager
- Stop sending messages from that number
- Review the exact reason in your BSP dashboard
- Submit an appeal through WhatsApp Manager
- Explain what happened and what you changed
- Add proof, such as opt-in forms or a cleaned contact list
Avoid generic appeals like “please restore my account.” Clear proof improves your chances.
Do not create a new number and continue the same activity. Meta may restrict that number too.
Warning Signs
Watch for:
- Falling delivery rates
- Quality moving from green to yellow
- Templates getting paused
- Read rates dropping
- Expected tier upgrades not happening
Fix your list quality and sending frequency before the restriction gets worse.
Media and Attachment Errors
Media errors usually happen because the file is too large, unsupported, or inaccessible.
Common issues:
- The file exceeds WhatsApp’s size limit
- The format or actual file type is unsupported
- The media URL is private, broken, or not HTTPS
- The uploaded media ID has expired
Related errors:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131053 | Media upload failed | Your media couldn't be uploaded, often due to a file type mismatch | Verify the MIME type, size, and URL, then re-upload |
| 131052 | Media download failed | WhatsApp couldn't download the media | Ask the user to resend it |
For frequently used files, upload the media once and reuse its media ID instead of relying on external links.
WhatsApp API Errors: Quick Troubleshooting Tips
When a message fails, check these points in order:
- Read the full error details, not just the code
- See whether the error affects all contacts or only some
- Check if your account is restricted
- Review your quality rating
- Confirm the template name, language, status, and variables
- Check whether the 24-hour window is open
- Verify the recipient number format
- Check your access token and webhook setup
Still stuck?
Save the fbtrace_id, timestamp, and full error response before contacting support.
How AiSensy Helps You Avoid WhatsApp API Errors
AiSensy helps prevent common WhatsApp API issues before they affect your campaigns.
- Checks templates before submission
- Alerts you when quality drops
- Shows clear delivery errors
- Handles retries and rate limits
- Displays the 24-hour window timer
- Supports verification and account setup
Start free and set up your WhatsApp Business API with fewer errors.
Conclusion
WhatsApp API errors may look technical, but most are easy to understand once you know what each code means.
To avoid frequent issues, focus on four things: collect proper opt-ins, segment your audience, avoid over-messaging, and monitor your quality rating.
Do this consistently, and WhatsApp API errors will become rare instead of routine.
FAQs
It means the 24-hour customer service window has closed - more than 24 hours have passed since that customer last messaged you. You can't send free-form messages anymore. Send an approved template message instead, and once they reply, the window reopens.
The most common reason is category mismatch - promotional content submitted as UTILITY. Other frequent causes are templates starting or ending with a variable, missing sample values, adjacent variables with no text between them, and broken URLs in buttons. Check the rejection reason in WhatsApp Manager, fix that specific issue, and resubmit.
Error 131026 usually means the number isn't on WhatsApp or is formatted incorrectly. Check that numbers are in full international format with no +, spaces or leading zeros - an Indian number should read 919876543210. If a large share of one campaign fails this way, it's a list formatting problem.
Restrictions (368, 131031) come from policy violations, sustained low quality ratings, or failed business verification. The exact reason appears in your Business Manager restriction notice. Stop sending, read the notice, fix the underlying cause, and appeal with evidence of what you've changed.
In Meta Business Manager, go to WhatsApp Manager → Phone Numbers, where each number shows a green, yellow or red rating. In AiSensy it's visible on your dashboard along with alerts when it changes.
It's an error 131047. WhatsApp opens a 24-hour window when a customer messages you, during which you can send free-form replies. Once it closes, only pre-approved templates are allowed.
Complete Business Verification to move from 250 to 2,000. Beyond that, Meta upgrades you automatically when you've used at least 50% of your current limit over 7 days and your quality rating is high. Meta evaluates every 6 hours.
Check in this order: is your account restricted, is your quality rating red, is the template approved and correctly referenced, are the numbers correctly formatted, and have you hit your messaging limit. The error code against each failed message narrows it down immediately.
Yes. Stop all promotional sending for about 7 days, keep only conversations customers initiate, audit your opt-in list, and resume gradually with well-segmented sends. Ratings are calculated on a rolling window, so old negative signals age out.
The recipient isn't on WhatsApp, their number is formatted incorrectly, their app is severely outdated, or their account is in a restricted state. Number formatting is by far the most common cause in bulk campaigns.
Display names must relate to your verified business or a brand you demonstrably own. Generic terms, URLs, phone numbers, emojis and promotional language are all rejected. Use your registered business name, or a trade name your live website clearly supports.
Usually a few minutes, but it can take up to 24 hours during high-volume periods like festive season. Submit campaign templates at least 48 hours ahead of when you need them.
Error 131048. Too many of your recent messages were blocked or reported, so Meta throttled your sending. Stop immediately, identify which template or segment caused the blocks, clean your list, and resume at lower volume.
Error 132015 pauses a template for 3 hours on first offence, 6 on second, 24 on third. It resumes automatically. Use the time to fix the cause - usually list quality or frequency. After too many pauses it's permanently disabled (132016) and you'll need a new template with different content.
Start with your BSP - AiSensy customers get direct support and most issues resolve there. For account restrictions and appeals, you'll need Meta directly through Business Manager. Always have the fbtrace_id and timestamp ready.
Quick Links
- How to Apply for WhatsApp Business API?
- WhatsApp Message Templates: Guide & Examples
- How to Send 1000 WhatsApp Messages at Once, Safely?
- How to get Free WhatsApp Green Tick in 4 Easy Steps
- WhatsApp Business API Pricing 2026
- WhatsApp Chatbot: What It Is and How to Build
- Top 12 WhatsApp Business API Use Cases