Every WhatsApp API error is trying to tell you something. This guide decodes every major error code what it actually means, why it fires, and exactly how to fix it, so you stop guessing and start shipping.
What WhatsApp API Errors Actually Are
Here’s the thing most devs don’t realise early on: errors on the WhatsApp Cloud API aren’t bugs they’re designed behaviour. Every time your backend sends a request to Meta’s Graph API, WhatsApp runs a full checklist behind the scenes:
- Is the access token valid?
- Does the app have the right permissions?
- Is the template approved for this language?
- Is the recipient within the 24-hour window?
- Have you hit your rate limit?
- Is the business account in good health?
- Is billing active?
If anything in that chain fails, you get an error. Your job isn’t to prevent errors entirely it’s to handle them correctly.
Sync vs. Async: Some errors come back instantly (synchronous) in the API response. Others arrive later via webhook — even when the initial API call returned 200 OK. Production systems must monitor both. Don’t just watch your API responses.
How to Read an Error Response
Before diving into specific codes, here’s what a real WhatsApp error looks like:
json
{
“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”
}
}
The rules for reading this:
- Build logic around code — not the message title. Titles are being deprecated by Meta.
- Read error_data.details — this is where the real explanation lives.
- Always log fbtrace_id — you’ll need it if you escalate to Meta or your BSP support.
- Ignore error_subcode — it’s deprecated and unreliable.
Don’t rely on error titles. Meta’s documentation explicitly warns that code titles (like “Rate limit hit”) will eventually be deprecated. Always key your logic to the numeric code value.
1. Auth & Permission Errors
These happen before a single message is sent. Until resolved, nothing goes through. Auth errors mean your application can’t properly identify itself to the WhatsApp Cloud API either the token is expired, revoked, or the app simply doesn’t have the right scope.
| Code | HTTP | What’s Happening | Most Likely Cause | Fix It |
| 0 | 401 | AuthException | Expired or revoked access token | Generate a fresh access token |
| 190 | 401 | Access token expired | Token lifetime exceeded | Refresh your token; set up auto-rotation |
| 10 | 403 | Permission denied | Missing scope or eligibility issue | Verify scopes in the Access Token Debugger |
| 200–299 | 403 | API permission issue | Endpoint access not enabled | Enable required permissions in App Dashboard |
Pro tip: If you’re getting Code 190 regularly, set up token rotation before expiry rather than reacting to failures in production. Use a System User token for long-running production deployments they don’t expire the same way user tokens do.
2. Integrity & Policy Enforcement Errors
Account-level restrictions. These aren’t quick fixes they require compliance review. These fire when something at the account level is wrong usually a policy violation or geographic restriction. They’re rare but high-impact. If you see these in production, it’s not a code bug; it’s a compliance issue.
| Code | HTTP | What’s Happening | Most Likely Cause | Fix It |
| 368 | 403 | Temporarily blocked | Policy violation flagged | Review Meta policy enforcement and appeal |
| 130497 | 403 | Country restricted | Sending to a region where messaging is not allowed | Verify allowed countries in your WABA settings |
| 131031 | 403 | Account locked | Policy issue or incorrect 2-step PIN | Use the Health Status API; contact support if unresolved |
3. Rate Limit & Throttling Errors
The most common errors in high-volume production. Expect these build for them. Rate limits are Meta’s way of maintaining messaging quality across the platform. Every business account has throughput ceilings. In high-volume campaigns or busy OTP windows, these errors will happen. The question is whether your system recovers gracefully or fails loudly.
If you’re running WhatsApp alongside SMS for OTP fallback, understanding how throughput works across both channels matters — our guide on the WhatsApp Business API in India covers WABA account structure, quality ratings, and how throughput limits work in the Indian market in detail.
| Code | HTTP | What’s Happening | Cause | Fix It |
| 4 | 400 | Too many API calls | App-level call rate exceeded | Throttle API frequency; use a queue |
| 80007 | 400 | WABA rate limit | Business account messaging limit hit | Slow your send rate; contact BSP to raise limits |
| 130429 | 400 | Rate limit hit | Cloud API throughput ceiling exceeded | Implement exponential backoff |
| 131048 | 400 | Spam rate limit | High block rate / low template quality | Improve template relevance; reduce send frequency |
| 131056 | 400 | Pair rate limit | Too many messages sent to one user | Space out messages to same recipient |
| 133016 | 400 | Registration limit | Too many registration attempts | Wait for the block to lift; don’t retry rapidly |
For 130429 specifically — implement exponential backoff. Start with a 1-second delay, then 2s, 4s, 8s, etc. Never hammer the API repeatedly after this error. Your throughput tier improves automatically as your quality rating grows.
4. Template Creation Errors (2388xxx Series)
These fire at template submission before any message is sent. They’re formatting and policy issues. If your template gets rejected before approval, you’ll see a 2388xxx error. These have nothing to do with sending — they’re about how you’ve written the template. Most are structural or length issues.
| Code | What’s Happening | Cause | Fix It |
| 2388040 | Character limit exceeded | A field is too long | Reduce content length in the offending field |
| 2388047 | Header format incorrect | Invalid header syntax | Review header format rules; rewrite header |
| 2388072 | Body format incorrect | Formatting violation in body | Adjust formatting — avoid unsupported markdown |
| 2388073 | Footer format incorrect | Footer structure issue | Review footer guidelines; rewrite footer |
| 2388293 | Too many variables | Parameter count exceeds ratio limit | Reduce number of {{N}} placeholders |
| 2388299 | Variable at start/end of field | Template starts or ends with a variable | Reposition — surround variables with fixed text |
Code 2388299 is sneaky. Meta doesn’t allow a template body to start or end with a variable like {{1}}. Always wrap variables with static text. Wrong: {{1}}, your OTP is 1234. Right: Hello {{1}}, your OTP is 1234. For a deeper look at how to write templates that pass Meta review and keep quality ratings high, check out our WhatsApp Message Templates guide for India.
5. Template Sending Errors (132xxx Series)
The most common production errors. Master these and you’ll solve 80% of message delivery failures. These fire when you try to send an approved template and something doesn’t match up wrong parameter count, wrong language code, paused template, or policy violation in the content.
| Code | HTTP | What’s Happening | Cause | Fix It |
| 132000 | 400 | Param count mismatch | Wrong number of variables passed | Match your parameters to the template exactly |
| 132001 | 404 | Template not found | Wrong template name or language code | Double-check template name and language in the Manager |
| 132005 | 400 | Hydrated text too long | Dynamic variable values make the text too long | Shorten the values you’re injecting into the template |
| 132007 | 400 | Policy violated | Disallowed content in the template | Revise template to comply with Meta’s commerce policy |
| 132012 | 400 | Param format mismatch | Wrong parameter type | Align parameter types with the approved template spec |
| 132015 | 400 | Template paused | Low quality rating — too many blocks/reports | Improve template quality; use warm-up strategy; resubmit |
| 132016 | 400 | Template disabled | Repeated violations; permanent pause | Create a new, compliant template — this one is done |
| 132068 | 400 | Flow blocked | WhatsApp Flow configuration issue | Audit your flow config and fix the blocked step |
| 132069 | 400 | Flow throttled | Too many flow messages sent in a short window | Reduce flow send frequency; add delays |
Error 132015 is the big one. A paused template means Meta saw an unusually high block/report rate during template pacing. This isn’t just a code fix it’s a signal that your audience doesn’t want this message. Fix the template relevance first, then think about resubmitting. Warm up new campaigns slowly: start with 1,000–5,000 sends, wait 24 hours, check reactions, then scale. Understanding the strategy behind warm-up, quality ratings, and keeping templates in the green zone is covered in our WhatsApp Broadcast Messaging guide for India.
6. Conversation Window Errors
These fire when you break the 24-hour messaging rule — one of WhatsApp’s core policy pillars. WhatsApp’s customer service window works like this: once a user messages your business, you have 24 hours to send free-form replies. After that window closes, you can only re-engage with a pre-approved template. If you try to send a free-form message outside the window, you’ll hit these errors.
| Code | HTTP | What’s Happening | Cause | Fix It |
| 131047 | 400 | 24-hour window closed | Outside the conversation window; tried sending free-form | Switch to a pre-approved template message instead |
| 131049 | 400 | Not delivered by Meta | Marketing message limits or pacing decision by Meta | Wait 24 hours; review your quality and pacing signals |
| 131050 | 400 | User opted out | Recipient blocked or opted out of your marketing messages | Do not retry; remove this user from future campaigns |
Error 131050 is a permanent stop signal. When a user opts out of marketing, you must stop sending to that number. Retrying will harm your quality rating and may escalate to a broader account restriction.
7. Media Errors
Media failures are usually infrastructure issues, not code bugs. When you send images, videos, or documents through the API, Meta needs to be able to fetch that media from your server. If the URL is private, the file is too large, or the MIME type is wrong, the download fails.
| Code | HTTP | What’s Happening | Cause | Fix It |
| 131052 | 400 | Media download error | Meta can’t fetch media from your URL | Ensure the media URL is publicly accessible; check server capacity |
| 131053 | 400 | Media upload error | Unsupported file type or MIME mismatch | Validate file type and size (images: max 5MB; video: max 16MB) |
Quick checklist for media errors: Is the URL publicly accessible (no auth required)? Is the MIME type set correctly in your server headers? Is the file under Meta’s size limit? If all yes and errors persist, try batching smaller send volumes — server timeouts during large campaigns can trigger 131052.
8. Registration & Migration Errors
These usually appear during onboarding or number migration — not in steady-state operation.
| Code | What’s Happening | Cause | Fix It |
| 133010 | Phone number not registered | Number hasn’t been onboarded to the Cloud API | Complete the registration flow for this number |
| 133005 | PIN mismatch | Incorrect 2-step verification PIN | Reset your 2-step PIN through the Business Manager |
| 133008 / 133009 | Too many PIN attempts | Rapid, repeated PIN retries | Wait for the cooldown period before trying again |
| 2388103 | Migration failed | WABA account mismatch during migration | Ensure source and destination WABA accounts are aligned |
9. WABA & Account Errors
Billing and maintenance issues. Rare, but they stop all messaging when they hit.
| Code | HTTP | What’s Happening | Cause | Fix It |
| 131042 | 400 | Payment eligibility issue | Billing is inactive or credit line not set up | Add a valid payment method and set up a credit line in Meta Business Manager |
| 131057 | 500 | Account in maintenance mode | Throughput upgrade in progress | Retry after the maintenance window; typically resolves automatically |
10. Other Core Errors
General request validation and delivery failures that don’t fit a specific category.
| Code | HTTP | What’s Happening | Cause | Fix It |
| 100 | 400 | Invalid parameter | Misspelled or malformed request field | Validate your request against the API schema |
| 131008 | 400 | Required parameter missing | A mandatory field is absent from the request | Add the missing parameter; check API docs for required fields |
| 131021 | 400 | Recipient is the sender | Sending to the same number you’re sending from | Change the recipient phone number |
| 131026 | 400 | Message undeliverable | Not a WhatsApp number, or outdated app version | Verify the number; ask user to update their WhatsApp app |
| 131000 | 500 | Unknown error | Internal Meta failure | Retry after a delay; escalate with fbtrace_id if it persists |
About 131026 (Message Undeliverable): Meta intentionally doesn’t always disclose why a message is undeliverable — for privacy reasons. Possible causes include: the recipient has blocked your business, the number isn’t on WhatsApp, the user is in a restricted country, or they haven’t accepted Meta’s updated ToS. Don’t retry these indefinitely.
11. Marketing Messages API Errors
Stricter rules apply here — template category and eligibility matter more than anywhere else.
| Code | HTTP | What’s Happening | Cause | Fix It |
| 131055 | 400 | Method not allowed | Using a non-marketing template on the marketing endpoint | Switch to a template categorised as Marketing |
| 134100 | 400 | Only marketing supported | Wrong template category for this endpoint | Update template category to Marketing in the Manager |
| 134101 | 400 | Template syncing | Newly created template hasn’t fully synced yet | Wait 10–15 minutes after creation before using it |
| 134102 | 500 | Template unavailable | Sync or eligibility issue | Check your WABA onboarding status and re-verify template |
| 132018 | 400 | Template validation error | Parameter issue specific to the Marketing Messages API | Fix the parameter structure in your request payload |
| 1752041 | 400 | Duplicate onboarding | User was already invited to this flow | No action needed — this is informational, not a failure |
Production Debugging Checklist
When something breaks in production, work through it in this exact order:
- Check HTTP status code first — 400 means your request is wrong. 401/403 is auth/permissions. 500 is Meta’s side. Start here to narrow the search.
- Read the numeric error code — This is your real identifier. Not the message title — the number. Build all your retry/handling logic around this.
- Read error_data.details — The human-readable detail string usually gives you exactly what went wrong at the request level.
- Confirm conversation window status — Is the 24-hour window open? If not, you need to switch to a template — not debug the free-form message.
- Confirm template approval status — Go to the WhatsApp Manager. Is the template still Active? Or Paused/Disabled?
- Check current rate limits — Are you mid-campaign? Rate limit errors during bulk sends are common and usually self-resolving with backoff.
- Verify billing is active — Especially for new accounts or after plan changes — billing issues silently block all messages.
- Retry only when safe — Don’t retry auth errors, opt-out errors, or policy violations. Only retry rate limits and 5xx server errors — with backoff.
Best Practices to Reduce Errors in Production
Build logic around code, not title
Meta has said clearly that error titles will be deprecated. Your application should map numeric codes to actions — never parse the message string.
Implement exponential backoff for rate limits
Whenever you hit code 130429, 4, or 131056 — back off. Start with 1 second, double on each retry, and cap at 60 seconds. Hammering the API after a rate limit hit only makes things worse.
Always validate phone numbers in E.164 format
Every number you send to should be in full international format — like +919876543210. No spaces, no leading zeros. A badly formatted number is often the cause of silent delivery failures (code 131026).
Confirm template approval before every send
Before a bulk campaign, pull your template list via API and confirm the status is APPROVED. Templates can get paused by Meta at any time based on quality signals. Sending to a paused template wastes quota and may further hurt your quality rating.
Monitor webhooks continuously, not just API responses
Async errors arrive via webhook. If your system only checks API response codes, you’re blind to a whole category of failures. Subscribe to the messages webhook field and process every error block you receive.
Log fbtrace_id for every response
Every API response includes an fbtrace_id. Log it. When something unusual happens and you need to escalate to Meta or your BSP, this ID is the only way support can trace the specific request on their side.
Warm up new templates before scaling
Don’t launch a new marketing template to 100,000 recipients on day one. Meta’s pacing system evaluates quality in the first few thousand sends. Start with 1,000–5,000, wait 24 hours, check block/read rates, then scale. This is how you avoid code 132015. For OTP-specific delivery best practices and how to build a proper fallback flow, the WhatsApp OTP API Integration guide for India walks through retry logic and multi-channel fallback in detail.
Final Word
WhatsApp API errors aren’t the enemy they’re feedback. Each one is telling you something specific: your token expired, your template got paused, a user opted out, your send rate is too high. The businesses that build stable WhatsApp integrations aren’t the ones that never see errors. They’re the ones who know exactly what every error means and have a documented response for each one.
If you want to understand the full cost and infrastructure behind running WhatsApp at scale in India pricing tiers, conversation categories, and how to keep your API spend optimised our WhatsApp Business API pricing guide for India breaks it all down. And if you’re looking for a WhatsApp Business API partner in India that handles routing, quality monitoring, and compliance for you, MessageBot’s WhatsApp Business API is built exactly for that.
