KewbotIn short
WhatsApp Cloud API errors arrive as a number and a short message that rarely explains the real cause. Most fall into five families: payment and eligibility, policy and delivery, account restriction, registration and number, and templates and content. Below are the most frequent ones, each with what it means and how to fix it. Find the number you got in the index and jump straight to it.
The problem is the payment method or billing
131042 Business eligibility payment issue
"There is an issue with payment method / business eligibility"
One of the most common, and it almost always means the same thing: there's a problem with the payment method on the WhatsApp Business account. Expired card, declined, no funds, or a Meta credit line that isn't set up. If you manage client accounts, this is the one that shows up when a client's card fails and stops all their sends.
How to fix itGo to the WhatsApp billing settings in the affected account's Business Manager and check the payment method: card valid, verified, and funded. On client accounts, confirm payment responsibility is assigned correctly. Once the payment is fixed, sends resume on their own.
141006 Payment issue on the WABA
"There is an error with the payment configuration"
A variant of the above, aimed at the WABA's own payment setup. The health check (health_status) shows can_send_message: BLOCKED. Same root family: the account can't bill, so it can't send.
How to fix itCheck that the WABA has a valid payment method correctly linked in Business Manager. If you migrated providers recently, verify the credit line or card ended up properly attached to the new account.
Meta chose not to deliver the message
131049 Healthy ecosystem engagement
"This message was not delivered to maintain healthy ecosystem engagement"
The single most reported error. It's not a technical failure: Meta deliberately chose not to deliver that message. It's usually tied to the per-user marketing template limit: if that person already got a lot of marketing templates in a short window, Meta stops delivery to avoid overwhelming them. It also shows up when the user has low likelihood of engaging with marketing.
How to fix itDon't retry right away: resending immediately just repeats the error. Wait at least 24 hours before sending that template to that user again. Ultimately the fix is strategic: send less marketing and more relevant, segment better, and prefer utility templates (which don't hit this limit) when the message is transactional rather than promotional.
131026 Message undeliverable
"Message undeliverable"
A broad "could not deliver". Typical causes: the number isn't on WhatsApp or isn't reachable, the recipient never opted in to receive messages from your business, or the account doesn't meet some eligibility requirement for that send. Sometimes it also comes from a template category mismatch.
How to fix itVerify the number exists on WhatsApp and is well formatted (country code included, no "+" depending on the endpoint). Confirm you have opt-in for that contact. If it's a bulk send failing only on some, clean the list of invalid numbers instead of retrying the whole batch.
The account is restricted or locked
130497 Restricted from messaging in this country
"Business account is restricted from messaging users in this country"
Your WABA is restricted from messaging users in a certain country. New accounts can only message the countries they were approved for; sending to an unauthorized country triggers this error. Very common when you start out and try to message a number abroad.
How to fix itCross-country messaging unlocks by completing a scaling path and reaching the 2,000 messaging tier. It can take up to 30 days to unlock after you reach it. Note: for some destinations (for example Brazil and Indonesia) it may not unlock even after the scaling path. In the meantime, send only to approved countries.
131031 Business account locked / restricted
"Business account locked"
The account was restricted or locked, usually for policy violations or verification discrepancies: spam, content that breaks the rules, or something that triggered Meta's integrity review. Along with 130497 and 368, it forms the integrity/policy restriction family.
How to fix itCheck the account status in Business Manager and in WhatsApp Account Quality. If there's a flagged violation, fix the cause (slow down sends, bring content in line with policy) and file the appeal from the panel itself. Retrying the send won't help: the restriction has to be lifted first.
Problems with the number, registration, or name
131037 Display name approval required
"The number used does not have an approved display name"
The number you're sending from doesn't have an approved display name, or the one you set is still pending approval. Until the display name is approved, you can't send.
How to fix itSet the display name and wait for Meta's approval. Make sure it follows the naming guidelines (matches your brand, no promotions or odd characters). If you work with a BSP, they manage the name.
133005 / 133006 / 133010 Number registration
"Wrong PIN / re-verification needed / number not registered"
The 133xxx family is about registering the number on the Cloud API. 133005: wrong two-step verification PIN. 133006: the number needs re-verification. 133010: the number isn't registered on the API.
How to fix itFor 133005, enter the correct two-step verification PIN; if you don't have it (typical when migrating from a dead provider), you first have to disable two-step verification from the WABA owner's WhatsApp Manager. For 133006 and 133010, run the number registration on the API again. These are exactly the errors that show up when porting a number between providers.
Send rate, format, and flows
131048 / 130429 Rate limit (spam / throughput)
"Spam rate limit hit / Rate limit hit"
You're sending faster than allowed. 130429 is the general rate limit; 131048 is the spam rate limit (Meta detected a sending pattern that looks like abuse). They show up in large, poorly paced campaigns.
How to fix itLower the send cadence and use exponential backoff on retries (progressively longer waits), not immediate retries. Stagger large campaigns over time. If it's 131048, also review quality and opt-in: the pattern that triggered the "spam" flag usually comes from cold lists or overly aggressive sending.
131053 Media upload error
"Media upload error"
The media upload or download failed (image, PDF, audio). Frequent cause: the file URL redirects (301), requires a session, or Meta's media fetcher couldn't download it. In logs you sometimes see it next to HTTP 500/502 errors when downloading the file from the weblink.
How to fix itAvoid URLs that redirect or depend on session cookies: Meta's fetcher doesn't follow them well. Serve the file from a public, direct URL (a public object in a bucket, no signed or expiring URLs). Also check the size and format WhatsApp allows.
132018 Invalid template parameter
"Parameter format mismatch / invalid parameter"
The content you pass into a template variable doesn't match the expected format. Classic case: sending line breaks (\n), tabs, or certain characters inside a variable when the template doesn't allow them at that spot.
Clean the variable value: strip line breaks and control characters, respect the format (positional vs. named) the template was created with, and don't put content in a variable that belongs in the fixed body. If you need a long list, reformat it to fit the allowed format.
139000 Blocked by integrity
"Blocked by Integrity" (sometimes with a subcode)
Meta blocked an action (for example publishing a flow) via its integrity check. It usually appears with Flows or when operating in development mode with incomplete permissions.
How to fix itCheck that the app and account have business verification and full permissions, and that you're not hitting a development-mode limitation. If the subcode points to a Dev Mode limitation, complete app review and approval first. Also make sure the flow content doesn't violate policy.
⚠️ What's always worth saving before you escalate
When an error is beyond you and you have to escalate to support, always save this: the full code and message, the error_data.details, the fbtrace_id, the wamid (if Meta accepted the send), the number ID and the WABA ID, and if it was a template, its name and language. With that, support resolves it in one round; without it, they ask for everything and you lose days. Don't send the message content unless they explicitly ask for it.
Frequently asked questions
Why doesn't the error message explain the real cause?
Because Meta uses generic messages by design. The same code can have several concrete causes, and the short text rarely distinguishes them. That's why it's worth looking at error_data.details and the fbtrace_id, which give more clues than the title.
I got an error and retried anyway. Is that bad?
Depends on the error. Rate-limit ones (131049, 130429, 131048) get worse if you retry immediately: you have to wait and use backoff. Payment, restriction, or registration ones aren't solved by retrying: you fix the cause first (payment, appeal, re-registration).
Is there an official, complete list of all codes?
Yes, Meta publishes the full reference in its Cloud API documentation, and it changes over time (they add new codes, like 131064). This guide covers the ones that show up most in practice, not the hundreds that exist. For a rare one, the official reference is the source.
Most of my errors are payment or restriction ones. What do I do?
If they keep repeating, it's usually a sign the account needs order: payment method properly configured, healthy quality and opt-in, and limit scaling done right. Fixing the root once stops them from coming back in a chain.
Stuck on an error that won't budge?
We onboard and run accounts on WhatsApp Business API, with access to Meta direct support to escalate the cases that need it. If you're fighting an error, get in touch and we'll take a look.
Go to Kewbot →