Pricing

Every code in one place

WhatsApp API Error Codes: Every Code, Where It Arrives

Last checked · 18 min read

The short answer

A WhatsApp Cloud API error is identified by its numeric code, not its message text. Meta returns it in the response to your request, later on the messages webhook, or both, and recommends handling errors by code and details string. Some codes mean retry later, some never retry, and some affect the whole account (checked 13 November 2026).

The WabaCRM Message logs screen in a demo workspace, described as every message in and out with its delivery lifecycle and any error Meta returned: a search box, direction, status and source filters and a date range above rows of inbound and outbound messages, each with a time, contact, number, source and a delivered or read status.

What do WhatsApp API error codes tell you?

A WhatsApp Cloud API error code tells you which rule a request broke, and the number is the only part of the error you should build on. Meta says so directly:

"In general, Meta recommends that you build your app's error handling logic around code values and details payload properties. These properties and their values are more indicative of the underlying error." (Meta, WhatsApp error codes)

What the code does not tell you, on its own, is where it will turn up. Some errors come back in the response to your request. Others arrive later, on the messages webhook, after the send has already returned success. A few do both. That difference decides how your system has to be built, and it is the column most error lists leave out.

This page is the index for every error code this blog has written about, plus the common ones Meta documents that we have not yet covered in depth. Each row gives Meta's own description, where the error arrives, whether retrying can help, and the first thing to do.

WhatsApp Cloud API errors sorted by where they arrive and what they ask of you, from request errors you fix and resend, through limits you wait out, to account-level and opt-out codes that no retry can clear
The code says what broke. Where it arrives says whether your system ever saw it.

How do you read a WhatsApp Cloud API error?

Every Cloud API error has the same shape. Meta publishes it on the error-codes page:

{
  "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, and Meta ranks them for you:

Field What Meta says about it
code "Build your app's error handling around error codes instead of subcodes or HTTP response status codes."
details "Error description and a description of the most likely reason for the error."
error_subcode "Deprecated. Will not be returned in v16.0+ responses."
fbtrace_id "Trace ID you can include when contacting Direct Support."

The message field is "Combination of the error code and its title", and Meta adds that it recommends "that you do not rely on titles for your error handling logic as titles will eventually be deprecated" (Meta, WhatsApp error codes). So (#130429) Rate limit hit is for a human reading a log. The 130429 inside it is for your code. Keep fbtrace_id on every failure you store; it is the one thing Meta's support will ask for.

Does a 200 from Meta mean the message went out?

No, and this is the single most expensive misunderstanding in WhatsApp integrations. Meta's page on sending messages says of the success response:

"This response only indicates that the API successfully accepted your request — it does not indicate successful delivery of your message. You receive delivery status via messages webhooks instead." (Meta, Service messages)

The error-codes page says the same from the other side: "Cloud API errors are returned either synchronously as a Graph API response, asynchronously via Webhook, or sometimes through both methods." It names the two places on the webhook an error can appear, entry.changes.value.errors and entry.changes.value.messages.errors, and recommends that you "monitor both the Graph API response and the messages webhook for error handling" (Meta, WhatsApp error codes).

Meta also warns that a failure can lag: "If you send a message that fails (status set to failed), there could be a minor delay before you receive the webhook. Build in a small buffer before assuming the message was dropped." (Meta, Service messages)

In practice this means a send has three outcomes, not two: refused in the response, accepted and then delivered, or accepted and then refused on the webhook. The last one is where 131026, 131049 and 131050 live, and in our own platform it is also where account-level refusals such as 131042 and 131031 most often land. A row marked "sent" on the strength of a 200 is a guess until a delivered or read status arrives.

Why group failures by code and never by message text?

Because the message text changes and the code does not. Meta tells you titles will be deprecated, and the details string can carry recipient-specific words. If a failure report groups on the text, forty identical failures can become forty groups of one, and a summary that shows the first six silently hides thirty-four customers. We learnt that one on our own campaign report: grouping is now on the code, codeless failures go into one labelled bucket, and the rows are checked to add up to the failed count.

The same rule protects retries. A retry decision keyed on a phrase such as "rate limit" will also catch the 80007 request budget, which is about your management API calls and not about sending at all.

Which WhatsApp error codes are there, and what does each mean?

The table below groups codes by what they ask of you. The second column is Meta's own details text from its error-codes page, word for word, except where a row says otherwise. "Response" means the error comes back on the API call that caused it; "Webhook" means it arrives later on the messages webhook; "Not stated" means Meta does not say which, so watch both.

Code Meta's description Arrives · retry First move
Delivery and recipient
131026 Unable to deliver message. (Meta then lists three reasons.) Webhook · don't resend blindly Confirm the person can message your number and is on a current WhatsApp
131047 More than 24 hours have passed since the recipient last replied to the sender number. Not stated · no Send an approved template instead
131049 This message was not delivered to maintain healthy ecosystem engagement. Webhook · not for 24 hours Wait at least 24 hours before resending
131050 Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business. Webhook · never Mark the contact; subscribe to user_preferences
130472 Message was not sent as part of an experiment. Webhook · no Nothing to fix; read Meta's experiment page
130403 Unable to deliver the message. This business has blocked the end user on WhatsApp Not stated · no Unblock the user if the block was a mistake
131021 Sender and recipient phone number is the same. Not stated · no Send to a different number
131030 Not on Meta's error-codes page Not stated · after fixing Check you are not posting to Meta's test number
131051 Unsupported message type. Response or inbound webhook Outbound: fix the type. Inbound: ask the customer
131052 Unable to download the media sent by the user. Webhook · no Ask for the file another way
131053 Unable to upload the media used in the message. Webhook · after fixing Check the file's real MIME type
Templates and parameters
132000 The number of variable parameter values included in the request did not match the number of variable parameters defined in the template. Not stated · after fixing Count values, and check parameter_name on named templates
132001 The template does not exist in the specified language or the template has not been approved. Not stated · after fixing Match name, language code and account exactly
132012 Variable parameter values formatted incorrectly. Not stated · after fixing Send values in the template's declared format
132015 Template is paused due to low quality so it cannot be sent in a template message. Not stated · after approval Edit the template and wait for approval
132016 Template has been paused too many times due to low quality and is now permanently disabled. Not stated · never Create a new template
132007 Template content violates a WhatsApp policy. Not stated · no Read Meta's template review reasons
131008 The request is missing a required parameter. Not stated · after fixing Often a URL button variable with no value
131009 One or more parameter values are invalid. Not stated · after fixing Check each value against the endpoint reference
100 The request included one or more unsupported or misspelled parameters. Response · after fixing Read details; a line break in a variable is a common cause
132018 There's an issue with the parameters in your template. (Marketing Messages API) Not stated · after fixing Check the parameters on the Marketing Messages API
2388019 You have exceeded the maximum number of message templates you can have for this WhatsApp business account. Response · no Delete unused templates, or verify the portfolio
2388024 Not on Meta's error-codes page; arrives as code 100 Response · no Edit the existing template or add a language
2388040 A field in your template has exceeded the maximum character limit allowed. Response · after fixing Shorten the field details names
2388299 Variables cannot be at the start or end of the template. Response · after fixing Put fixed words before and after variables
2388293 This template has too many variables for its length. Reduce the number of variables or increase the message length. Response · after fixing Fewer variables, or more fixed text
2388072 Your message body contains invalid formatting. Response · after fixing Read the error message for the field
132068 and 132069 Flow is in blocked state. / Flow is in throttled state and 10 messages using this flow were already sent in the last hour. Not stated · after fixing Fix the Flow's endpoint health
Rate and messaging limits
131056 Too many messages sent from the sender phone number to the same recipient phone number in a short period of time. Not stated · yes, later Slow down to that one recipient
130429 Cloud API message throughput has been reached. Response · yes, later Send more slowly across the number
80007 The WhatsApp Business Account has reached its rate limit. Response · yes, later Cut polling of management endpoints
80008 Not on Meta's error-codes page Response · yes, later Handle exactly as 80007
4 The app has reached its API call rate limit. Response · yes, later Check the App Dashboard's rate limit section
131064 Message failed to send because this account has reached its messaging limit due to template classification violations. Not stated · after the period Correct template categories
131048 Paraphrased: the number is limited after previous messages were blocked or flagged as spam. Not stated · no Check quality in WhatsApp Manager
135000 Message failed to send because of an unknown error with your request parameters. Response or webhook Check which route it took first
Account, payment and policy
131042 There was an error related to your payment method. Webhook, in our experience · no Fix billing on your own WhatsApp Business Account
368 The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy. Not stated · no Check Business Support Home
131031 Paraphrased: the account is restricted or disabled, or data in the request (such as the two-step PIN) did not verify. Webhook, in our experience · no Check the Health Status API
130497 The WhatsApp Business Account is restricted from messaging to users in certain countries. Not stated · no Check allowed countries for your category
131037 The 555 business phone number used to send the request does not have an approved display name. Not stated · after approval Get the display name approved
131016 A service is temporarily unavailable. Not stated · yes, later Check the WhatsApp Business Platform Status page
2 Temporary due to downtime or due to being overloaded. Not stated · yes, later Check the status page before retrying
131000 Message failed to send due to an unknown error. Not stated · yes, once Retry; if it persists, open a support ticket
131057 Business Account is in maintenance mode Not stated · yes, later Wait; Meta names a throughput upgrade as one reason
Registration and numbers
131045 Message failed to send due to a phone number registration error. Not stated · after registering Register the number once, with its PIN
133016 Registration or Deregistration failed because there were too many attempts for this phone number in a short period of time Response · not until unblocked Stop calling /register
133005 Two-step verification PIN incorrect. Response · after fixing Set a new PIN; do not guess
133010 Phone number not registered on the WhatsApp Business Platform. Not stated · after registering Register the number
2388103 Nine different details strings share this code Response · depends Branch on details, never on the code
33 The business phone number has been deleted. Response · no Check the phone number id
Access tokens and permissions
190 Your access token has expired. Response · after a new token Issue a new token of the right type
0 We were unable to authenticate the app user. Response · after a new token Get a new access token
10, 131005, 200–299 Permission is either not granted or has been removed. Response · after granting Check the token in the access token debugger

Meta's error-codes page was last updated on 18 June 2026 when read on 13 November 2026. The "Webhook, in our experience" rows are what WabaCRM sees on its own platform; Meta does not say which route those two codes take.

How should your code decide whether to retry?

Sort every code into one of three buckets before you write a single retry loop, because the wrong bucket costs more than no retry at all.

Wait, then try again. Throughput and rate limits (130429, 131056, 80007, code 4) and service problems (131016, code 2) describe something temporary. Back off and slow down. For 80007 and code 4, Meta's own advice is to reduce the frequency or amount of API queries, so the fix is fewer management calls, not a faster retry.

Fix, then resend. Template and parameter errors (132000, 132001, 132012, 131008, 100 and the 2388 family) will fail identically every time until the request changes. Retrying them only adds noise to your logs. Stop, surface the details string to whoever owns the template, and resend once it is fixed.

Stop. An opt-out (131050) is permanent for marketing. A closed window (131047) needs a template, not the same message again. After 131049, Meta says to wait at least 24 hours. Account-level codes (131042, 368, 131031, 130497, 131064) will refuse every recipient until the account is fixed, so pause sending from that number rather than failing a campaign one customer at a time. And never let a loop call /register: repeated attempts are exactly what produce 133016, as our registration-loop post explains.

One lesson from running this on our own platform: once an account-level refusal is recorded, clear it only when a message is actually delivered or read. A 200 on the next send proves nothing, because the refusal may simply arrive on the webhook a few seconds later.

Which errors come from Embedded Signup rather than the API?

Errors raised while a business connects its number are not on the API error-codes page at all. They appear inside Meta's signup window and are listed on a separate page, Embedded Signup Flow Errors, last updated 10 November 2026 when read on 13 November 2026.

Code Meta's description First move
2655093 The business is already sharing this WhatsApp Business account with a partner. Switching partners is not supported in this flow. Disconnect the current partner in the WhatsApp Business app
1752206 The user cannot be added to the business. Contact Business Support
3441061 Your phone number is already linked to Automatic Events. Turn off Auto lists in the Business app
3441049 This phone number is already registered with the product. Disconnect it in the app's Business Platform settings, wait 15 minutes
2655121 You cannot proceed with this operation since your WhatsApp Business account is currently restricted. Resolve it at Business Support Home

One detail on 3441061 is worth knowing. When the code reached us from Meta's window in September 2026, it told us to turn off Auto labels under Business tools > Labels. Meta's page now reads "turn off Auto lists in Business Tools > Lists in your WhatsApp Business app". The wording has changed since; look for whichever of the two your app version shows. Our full write-up of connection failures, including why typing the number beats picking it from a list, is in the coexistence ineligible guide.

Which WhatsApp error codes are missing from Meta's page?

Several codes developers actually receive are not on the error-codes page as read on 13 November 2026, which is why searching them returns pages that repeat the error string and stop.

  • 131030, the allowed-list error from Meta's test sender number.
  • 80008, which Meta's Graph API rate-limiting page lists against the WhatsApp Business Management API, and the WhatsApp error page does not mention at all.
  • 2388024 and other template refusals that arrive as subcodes of code 100.

Two others have more than one documented meaning. 135000 is "an unknown error with your request parameters" on the error-codes page and, as our 135000 write-up sets out, also the code Meta's business portfolio pacing page uses for held template messages it drops. 2388103 has nine rows, told apart only by their details string. For both, the code alone is not enough to act on.

What about webhook failures that have no error code?

Some of the hardest WhatsApp problems never produce an error code, because the failure is that nothing arrives. Meta will not validate your callback URL unless the endpoint returns hub.challenge as plain text; signatures fail to match if you hash parsed JSON rather than the raw body; and a verified webhook still receives nothing until each WhatsApp Business Account is subscribed to your app.

Each has its own page: why Meta cannot validate your callback URL, why X-Hub-Signature-256 never matches, a verified webhook that receives nothing and how long Meta retries a failed delivery. If the dashboard says connected and nothing is sending, start with that checklist before reading any code.

How does WabaCRM show these errors?

Every message in a WabaCRM workspace, in either direction, sits in the message logs with its delivery status and any error Meta returned, and a refusal is explained in plain words rather than in Meta's raw text. Refusals that belong to the account rather than the message, such as a payment or policy code, are raised once on the number's card instead of once per customer.

The WabaCRM Message logs screen in a demo workspace, with search, direction, status and source filters and a date range above rows of inbound and outbound text messages, each showing the time, the contact's name and number, the WhatsApp number used, the source and a delivered or read status
A message's status comes from the webhook, not from the send, so this list is the record of what Meta actually did.

The number's card also repeats Meta's own health check, so an account-level problem is visible before a campaign runs into it.

A WhatsApp number card in a demo workspace marked Not receiving messages, quoting Meta's health check that the app is not subscribed to the message webhook, with steps to check the partner listing in Business settings, a note that the account moved to another business portfolio, and the quality rating, messaging tier, template count and last check time beneath
When the problem is the account, the number says so once, instead of every message failing on its own.

WabaCRM is a Meta-verified Tech Provider, so payment errors such as 131042 are fixed on your own WhatsApp Business Account, where Meta bills you directly. If you run your sends from another tool through our API, the n8n and Zapier integration guide shows where those codes come back.

Every Meta quotation on this page was read from Meta's own documentation on 13 November 2026. Meta changes that documentation without notice; the linked pages are authoritative and this one is not.

Frequently asked

Does a 200 response from the WhatsApp Cloud API mean the message was delivered?

No. Meta's documentation says the response to a send only indicates that the API successfully accepted your request and does not indicate successful delivery, and that delivery status arrives on the messages webhook instead. Several of the commonest failures, including 131026, 131049 and 131050, arrive that way, seconds after a send that returned 200 and a message id. A system that records the send result and never reads the status webhook will show those messages as sent for ever.

What is the difference between code and error_subcode in a WhatsApp API error?

The code is the number to build your handling on. Meta's error-codes page calls error_subcode deprecated and says it will not be returned in v16.0 and later responses, and it advises building error handling around the code and the details property instead. Some older Graph errors still carry a subcode, which is why template creation refusals such as 2388024 appear as code 100 with a subcode. Where both are present, branch on the code first and read the details string for the specific cause.

Which WhatsApp error codes affect the whole account rather than one message?

The payment error 131042, the policy codes 368 and 131031, the country restriction 130497, the template classification limit 131064 and the spam-related limit 131048 all describe the WhatsApp Business Account or the number rather than one recipient. Retrying the message changes nothing until the account-level cause is fixed, usually in WhatsApp Manager, Business Support Home or the billing settings of your own Meta business portfolio. An expired access token, code 190, also stops every call until a new token is issued.

Should I retry a WhatsApp message that failed?

Only for the codes that describe something temporary. Throughput and rate limits such as 130429, 131056, 80007 and code 4, and service outages such as 131016 and code 2, are worth retrying later and more slowly. A closed window, 131047, needs a template rather than a retry. An opt-out, 131050, should never be retried, and Meta tells you to wait at least 24 hours after 131049. Retrying a payload error such as 132000 sends the same mistake again.

Why is my WhatsApp error code missing from Meta's error codes page?

Because that page is not complete. As read on 13 November 2026 it does not list 131030, which comes from Meta's test number, or 80008, which appears on Meta's general Graph rate-limiting page instead. Template refusals such as 2388024 arrive as subcodes of code 100, and Embedded Signup errors live on a separate page of their own. When a code is missing, read the details string in the response, which is the part Meta says is most indicative of the cause.

Related guides

See every refusal in plain words

₹999 once for 1,000 contacts — no monthly fee and no expiry. Signing up is free and needs no card, so you can connect your number and read what arrives before you pay. Connecting takes as long as Meta's own review of it.

Sign up with any email address you check. No sales call, no onboarding fee, nothing to schedule.

Why this is safe to point your customer list at

Payments are processed by Razorpay on their own checkout — your card details are never entered on, or stored by, WabaCRM. Every inbound WhatsApp webhook is checked against its signature before it is trusted.

Tech Provider is a Meta platform access tier — not a partnership, a reseller agreement or an endorsement.