WhatsApp API Error Codes Explained: A Practical Troubleshooting Guide (2026)

Key Takeaways

• Every WhatsApp Cloud API error arrives as a code, a details string, and a fbtrace_id. Meta explicitly recommends building your error handling around code and details — not the message title, since titles are being phased out.

• Errors show up in two different places: some fail immediately in the API response when you make the call; others are accepted by Meta and only fail later, reported asynchronously inside a messages webhook. A robust integration watches both.

• Most errors cluster into a handful of categories: authorization/token issues, throttling and rate limits, template and messaging-window problems, phone number registration, payment/billing, and recipient-side delivery failures.

• Some "errors" — like 131049 and 131050 — aren't bugs in your setup at all. They mean the recipient's own preferences or Meta's ecosystem-health limits are the reason delivery didn't happen, and retrying immediately won't help.

• Graph API rate limits (error 4, 80007) can't be raised by request — the fix is reducing call frequency or improving message quality, not asking Meta for an exception.

If you've built anything on the WhatsApp Business Platform, you've hit one of these at some point: a template that silently fails, a token that stops working overnight, a broadcast that sends fine for 200 contacts and then throws errors for the rest. None of it is random. Every code maps to a specific, documented cause, and once you know which bucket an error falls into, the fix is usually a five-minute job rather than a guessing game.

This guide organizes the errors you're most likely to run into by what's actually going wrong, so you can jump to the right section instead of scanning a flat list.

First, Understand How an Error Reaches You

Before troubleshooting any specific code, it helps to know that the WhatsApp Cloud API — built on top of Meta's Graph API — can fail in two structurally different ways:

Synchronous failures happen the moment you make the API call. Meta rejects the request outright and hands the error straight back in the HTTP response. Malformed parameters, an expired token, or a request that violates the API's structure typically fail this way — you find out instantly.

Asynchronous failures happen after Meta has already accepted your request. The call itself returns success, but the message fails to actually reach the recipient for some downstream reason — a closed messaging window, a recipient-side block, or a per-user delivery cap. These show up later, inside the errors array on a messages webhook event, not in your original API response.

This distinction matters because a lot of "why didn't this send?" confusion comes from only checking one side. A request can pass every synchronous check, return a clean 200 response, and still never reach the customer — you'll only see why if you're also subscribed to and parsing the webhook.

Reading the Error Object Itself

A typical Cloud API error looks like this:

json

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput has been reached."
    },
    "error_subcode": 2494055,
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

Four fields matter in practice:

• code — the stable numeric identifier. This is what your error-handling logic should branch on.

• error_data.details — a plain-language explanation, often the most useful field for figuring out exactly what tripped the error.

• error_subcode and the wording inside message — useful for a human reading logs, but Meta has deprecated error_subcode in newer API versions and explicitly warns that title wording can change. Don't build conditional logic around it.

• fbtrace_id — hand this to Meta support if you need to open a ticket; it lets them pull the exact request server-side.

Quick-Reference Table

Authorization and Access Errors

These fail every call, not just one message, which is usually the tell that you're in this category.

Code 0 / 190 — token expired or invalid. The access token attached to your request has expired, been revoked, or the app user changed a permission setting. Pull a fresh system-user token (these don't expire the way short-lived developer tokens do) and update wherever it's stored.

Code 10 / 200–299 — permission not granted. Your app has a valid token but lacks the specific scope the endpoint requires — commonly whatsapp_business_messaging or whatsapp_business_management. Run the token through Meta's access token debugger to see exactly which scopes are attached, then re-grant what's missing.

Code 3 — capability/permissions issue. Similar territory to the above; usually resolved the same way, by checking scopes against what the specific endpoint needs.

Throttling and Rate-Limit Errors

This is the category most teams confuse, because "rate limit" gets used for at least four genuinely different mechanisms.

Code 4 — app-level API call limit. This has nothing to do with how many messages you've sent to customers. It's about how often your app hits the Graph API itself — template syncs, status checks, management calls. If you're polling an endpoint in a loop, add caching and space the calls out. This ceiling can't be raised on request; the fix is always to call less often.

Code 80007 — WhatsApp Business Account rate limit. A related but account-scoped version of the same idea. Reduce query frequency across everything that account is doing.

Code 130429 — Cloud API message throughput. This is the messages-per-second ceiling, separate from your daily conversation limit. A burst send that outpaces your account's throughput tier trips this. Queue sends through a scheduler instead of firing them all at once; the ceiling itself rises automatically as your number earns a higher quality-and-volume tier.

Code 131048 — restricted after negative signals. This isn't a technical throughput issue — it's Meta capping how much you can send because recent messages generated blocks, reports, or spam flags. Check your quality rating in WhatsApp Manager, pause broad campaigns, and go back to messaging only people with a clear, recent opt-in. This eases as your quality rating recovers; there's no override.

Code 131056 — pair rate limit. Too many messages, too fast, to one specific recipient. Usually caused by a bot re-sending on every retry or a workflow that fires multiple templates back-to-back. Combine content into fewer sends and add a per-recipient cooldown.

Code 131064 — messaging limit tied to template misclassification. If templates are being sent under the wrong category (a promotional message tagged as Utility, for instance), Meta can apply this restriction. Review your template categories against their actual content; the restriction lifts automatically after the enforcement period once corrected.

Messaging Window and Template Errors

Code 131047 — the 24-hour window closed. You're trying to send a free-form message, but more than 24 hours have passed since the customer's last message to you. There's no way around this except sending an approved template — once they reply to it, the free-form window reopens.

Codes 132000 and 132012 — parameter mismatch. The number of variables you sent doesn't match what the approved template expects, or the format of a variable (a date, a currency value) doesn't match what was approved. Line up your request payload against the exact template definition in WhatsApp Manager.

Code 132001 — template not found or unapproved. Usually a mismatch between the template name or language code in your request and what's actually approved. Double-check both against WhatsApp Manager, since template names are case- and locale-sensitive.

Code 132007 — content policy violation. The template itself was rejected for violating WhatsApp's content policies. Review the rejection reason and resubmit with adjusted copy.

Codes 132015 and 132016 — paused or disabled for low quality. A template that keeps generating negative feedback gets paused first (fixable by editing and resubmitting) and permanently disabled if it happens repeatedly (at which point you need a new template, not an edited one).

Registration and Phone Number Errors

Code 131045 / 133010 — registration error. The number isn't correctly registered on the platform, often because a consumer WhatsApp app is still linked to it, or a prior registration attempt didn't complete cleanly. Re-run the registration flow after confirming the number isn't still active in the regular WhatsApp app.

Codes 133005, 133008, 133009 — two-step verification PIN issues. Wrong PIN, too many wrong guesses, or guesses submitted too quickly. Reset the PIN by disabling and re-enabling two-step verification if you're locked out, and respect the cooldown window Meta specifies in the error details before trying again.

Code 133000 — failed deregistration. A previous attempt to deregister the number didn't finish. Deregister again cleanly before attempting to re-register.

Code 133016 — too many registration attempts. Repeated registration/deregistration cycles in a short window trigger a temporary block on that number. Wait it out rather than retrying immediately.

Payment and Account Errors

Code 131042 — payment issue. This one has several possible root causes worth checking in order: no payment account attached to the WhatsApp Business Account, a credit line that's over its limit or inactive, missing timezone or currency settings, or an unapproved "messaging on behalf of" request if you're a solution provider. Work through Business Manager's payment settings section by section — the details field in the error response usually narrows it down.

Code 368 — account restricted for a policy violation. More serious than a billing hiccup: the WhatsApp Business Account itself has been restricted. Review Meta's policy enforcement documentation for the specific violation category and next steps.

Code 130497 — country messaging restriction. Your business category isn't permitted to message users in the recipient's country under WhatsApp's business messaging policy. This isn't fixable per-message; it requires a different messaging approach for that market.

Delivery and Recipient Errors

Code 131026 — recipient can't receive the message. Several possible causes bundle into this one code: the number isn't actually on WhatsApp, the recipient hasn't accepted WhatsApp's current Terms of Service, or they're on an outdated client version. Since you can't message them to ask (that's the problem), reach out through a non-WhatsApp channel if you need to confirm.

Code 130403 — you've blocked this user. Self-explanatory, but easy to overlook if blocking happened somewhere else in your stack. Unblock via the API to resume.

Code 131050 — recipient opted out. The user has explicitly told WhatsApp they don't want marketing messages from your business. This is a hard stop, not a rate limit — don't retry, and consider subscribing to the user_preferences webhook so your system automatically suppresses future sends to anyone who opts out.

Code 131049 — ecosystem health / per-user frequency cap. Distinct from 131050: this isn't the user opting out of your business specifically, it's Meta's adaptive cap on how many marketing templates any one person receives across every business messaging them. Meta's own guidance is explicit — wait at least 24 hours before resending to that contact, since an immediate retry just produces the same failure.

Codes 131052 and 131053 — media download or upload failure. Either the media a customer sent you couldn't be downloaded, or media you tried to send couldn't be uploaded (often an unsupported MIME type or an expired URL). Check the file type against WhatsApp's supported media list before sending.

Parameter and Request Errors

Code 100 — unsupported or misspelled parameter. The request includes a field the endpoint doesn't recognize, or a typo in a field name. Cross-check against the specific endpoint's reference rather than assuming the shape of a similar endpoint.

Code 131008 — required parameter missing. Something like to, type, template.name, or language wasn't included. The details field usually names exactly which field is absent.

Code 131009 — invalid parameter value. The field is present but the value doesn't match what's expected — wrong phone number format, an unsupported language code, or a value outside the template's defined format.

Code 131021 — sender and recipient are the same number. Exactly what it sounds like; make sure your test environment isn't accidentally sending a business number a message from itself.

Server-Side and Unknown Errors

Codes 1 and 2 — generic or temporary server error. Before assuming it's something in your request, check the WhatsApp Business Platform status page for an active incident. If nothing's reported there, review your request format next.

Code 131000 — unknown send failure. A catch-all for failures that don't map to a more specific cause. Retry once; if it persists, open a support ticket with the fbtrace_id attached.

Code 131016 / 133004 — temporary unavailability. Downtime or an overloaded service on Meta's end. Retry after a short delay rather than immediately looping.

Building Error Handling That Doesn't Break Every Update

A few habits make WhatsApp API error handling meaningfully more resilient:

• Branch on code and details, never on the message title. Meta has said plainly that title wording isn't stable and error_subcode is being phased out — logic built around exact string matching on the title will eventually break silently.

• Subscribe to and parse the messages webhook, not just API responses. A clean synchronous response only tells you Meta accepted the request, not that it was delivered.

• Treat 131049 and 131050 as "don't retry now" signals, not bugs. Immediate retries on these two specifically just produce more failures and don't help your account's standing.

• Log the fbtrace_id on every failure. It costs nothing to store and saves real time if you ever need Meta support to look at a specific request.

• Separate "fix the request" errors from "fix the campaign" errors. A parameter or auth error is a code problem; a 131048 or 131056 pattern is a messaging-behavior problem, and no amount of retry logic solves it — only sending fewer, better-targeted messages does.

Where TalkWhy Fits Into This

Most of these errors are Meta's rules, not something a platform can bypass — but a lot of the operational pain around them comes down to visibility and consistent template hygiene, which is where TalkWhy's WhatsApp tooling is built to help:

• A shared WhatsApp inbox that surfaces failed and undelivered messages in one place, so a 131047 or 131026 doesn't get lost in an individual agent's chat window.

• Knowledge-base-trained automated replies that reduce reliance on broad, generic marketing templates — the exact category of send most likely to trigger 131048 or 131049 in the first place.

• Automation rules for structured, paced follow-ups instead of rapid-fire sends to the same contact, which is precisely what avoids 131056.

• A developer API if your team wants to build custom webhook handling, retry logic, or delivery-status dashboards on top of the platform.

• Role-based permissions with MFA, so token and account access stays controlled as more team members touch the WhatsApp connection.

• SOC 2 Type II compliance and AES-256 encryption for the underlying security posture.

You can try these on a free trial with no credit card required, and current plan details are on the TalkWhy pricing page.

Frequently Asked Questions

What's the single most useful field in a WhatsApp API error for debugging?

error_data.details. The numeric code tells you the category; details usually tells you the specific reason in plain language, and sometimes names the exact parameter or condition involved.

Why did my API call return success, but the customer never got the message?

The call succeeding only confirms Meta accepted the request. Delivery failures that happen afterward — a closed messaging window, a recipient-side block, a frequency cap — are reported separately, inside the errors array of a messages webhook event. You need to be subscribed to that webhook to see them.

Is error 131049 the same as being rate-limited on my account?

No. It's a per-recipient cap that applies across every business messaging that specific person, not a reflection of your account's own quality or tier. Your account can be perfectly healthy and still see 131049 on individual sends.

Can I ask Meta to raise my API call rate limit (error 4)?

No — Graph API call limits aren't adjustable on request. The only lever is reducing how often your app calls the API, typically through caching and batching.

My template was approved — why is it still failing to send?

Approval only confirms the content passed review. Delivery can still fail separately due to throughput limits, the recipient's messaging window, per-user frequency caps, or the template later being paused for low quality after approval. Approval and deliverability are checked at different points.

How long do I need to wait before retrying after a 131049 or 131056 error?

Meta's guidance for both is at least 24 hours. Retrying sooner typically just returns the same error, since the underlying limit is still in effect.

Should I still handle error_subcode in my code?

Not as your primary logic. Meta has deprecated it in newer API versions and recommends building error handling around code and details instead, since those are guaranteed to remain stable.