WhatsApp Cloud API error codes, and which ones you should never retry

Meta documents well over a hundred error codes. Perhaps fifteen of them ever reach a production send pipeline, and the difference that matters about each one is not what it means. It is whether retrying is sensible or self-harm.

Every code below comes from Meta's published error reference. What is ours is the retry column, which is where the money is.

Which WhatsApp errors are safe to retry?

Only the ones caused by a limit or a queue, never the ones caused by the recipient.

Code	What happened	Retry?
`130429`	Cloud API throughput exceeded. You sent faster than your account is allowed to.	Yes. Back off and slow down.
`131049`	Meta blocked this message to protect the recipient's experience, the per-user marketing cap.	Yes, after 24 hours or more.
`131056`	Too many messages to the same recipient in a short window.	Yes for that number later. Other numbers are unaffected right now.
`4`	Your app hit its API call rate limit.	Yes. Reduce call frequency.
`80007`	The WhatsApp Business Account hit its rate limit.	Yes. Slow down.
`133004`	Server temporarily unavailable.	Yes. Straightforward transient failure.
`131048`	Sending restricted because of previous blocks or spam reports.	Not yet. Fix quality first, in WhatsApp Manager.
`131064`	Account hit a messaging limit because of template violations.	No. Lifts itself after the enforcement period.

Which WhatsApp errors must never be retried?

The ones where the recipient cannot or will not receive the message. Retrying these is pure cost with a quality penalty attached.

Code	What happened	Why retrying is wrong
`131026`	Not reachable. Not on WhatsApp, on a version too old, or refused by policy.	Nothing will change on a retry. This is the single biggest source of wasted quota on cold lists.
`131050`	The recipient opted out of marketing messages from you.	They asked you to stop. Subscribe to the `user_preferences` webhook and honour it.
`130403`	You have blocked this recipient.	Unblock them first, or stop sending.
`131021`	Sender and recipient are the same number.	A data bug, not a delivery problem. Fix the row.
`132016`	Template permanently disabled after being paused too often for low quality.	That template is finished. Write a new one.

Watch out: 131047 looks permanent and is not. It means more than 24 hours have passed since the customer last replied, so the customer service window is closed. The fix is not a retry of the same free-form message, it is sending an approved template instead.

There is a third category worth separating out: the credential errors, 0, 3, 10, 190 and 200. These are not delivery failures at all, and no retry policy will help, because the request never reached the point of being about a message. 190 in particular ("Your access token has expired") is the most common of all first-integration failures, and it almost always means a temporary token from the App Dashboard was shipped to production. The permanent token, and how to generate one covers the fix, plus the four non-time-based ways a "permanent" token still stops working.

The template errors, which are a different problem

These fail before delivery is even attempted, so they cost you nothing but a broken flow. They are almost always a mismatch between what you built and what you submitted, and the rules they are checking against are covered in why templates get rejected.

Code	What happened	Fix
`132000`	Number of variables in the request does not match the template.	Send a value for every parameter the template defines.
`132001`	Template does not exist in that language, or is not approved.	Check the name and the language locale. A missing `en_US` versus `en` is the usual culprit.
`132005`	Translated text too long.	Shorten it, then check the translation in WhatsApp Manager.
`132007`	Content violates a WhatsApp policy.	Read the review notes; the content has to change.
`132012`	Parameter values formatted incorrectly.	Match the format the template declares.
`132015`	Template paused for low quality.	Edit it and wait for reapproval.
`132068`	Flow is in a blocked state.	Fix the Flow configuration.
`132069`	Flow throttled, 10 or more messages in the last hour.	Fix the Flow configuration.

Where these actually show up

Not in the response to your send. This is the part that catches teams out.

A send returns 200 with a message ID, and the failure arrives later, over the status webhook, attached to that ID. So if you are not storing the returned wamid against your outbound row and subscribing to status webhooks, these errors are invisible to you and your dashboard will show a campaign that went out cleanly.

That is a different article: why "sent" means nothing in the WhatsApp Cloud API.

What to build instead of a retry loop

Classify on arrival. A failure webhook lands, you look up the code, and you set the row to retryable or dead. Never "failed".
Back off, do not hammer. For 131049, next day at the earliest. For 130429, slow the whole queue, not just this message.
Never retry a dead. Not on a schedule, not on a manual "resend all", not on a migration script. Those are the three places it always creeps back in.
Compare the code in your application, not in SQL. Ranking or matching an error code inside a query is how you get a runtime failure in the middle of a webhook handler, where nobody is watching.
Watch the quality rating, not the failure count. The failures are the symptom. The rating is what decides whether you can still send tomorrow.

At Kredoo this classification is not optional plumbing, it is the difference between a follow-up system that keeps working at volume and one that quietly gets throttled. If you would rather not build it, that is what we do.

Every WhatsApp Cloud API error code

The complete list, grouped the way Meta groups it. Every code has its own link, so you can send someone straight to the one they are staring at: blog.kredoo.in/whatsapp-error-codes/#e131049.

The description is Meta's. The Retry column is ours, and it is the reason this table exists rather than being a copy of the docs. Where the documented behaviour does not support a confident answer it says so instead of guessing.

Authorization

Code	What Meta says	Retry?
0	We were unable to authenticate the app user.	Fix first
3	Capability or permissions issue.	Fix first
10	Permission is either not granted or has been removed.	Fix first
190	Your access token has expired.	Fix first
200	No access token was provided.	Fix first

Integrity, meaning your account is restricted

Code	What Meta says	Retry?
368	Account restricted or disabled for a policy violation.	No
130497	Account restricted from messaging certain countries.	No
131031	Account restricted, or data verification failed.	No

Throttling and limits

Code	What Meta says	Retry?
4	App has reached its API call rate limit.	Yes
80007	WhatsApp Business Account rate limit reached.	Yes
130429	Cloud API message throughput has been reached.	Yes
131048	Message restricted due to quality status.	Fix first
131056	Too many messages sent to the same recipient in a short period.	Yes
131064	Messaging limit reached because of template violations.	No
133016	Too many registration attempts in a short period.	Yes

Delivery

Code	What Meta says	Retry?
130403	Business blocked the end user on WhatsApp.	No
130472	Message not sent as part of an experiment.	No
131000	Message failed to send due to an unknown error.	Yes
131005	Permission not granted or removed.	Fix first
131008	Request is missing a required parameter.	No
131009	One or more parameter values are invalid.	No
131016	Service temporarily unavailable.	Yes
131021	Sender and recipient phone number are the same.	No
131026	Unable to deliver the message: not on WhatsApp, an old app version, or refused on policy grounds.	No
131037	The 555 phone number lacks an approved display name.	Fix first
131042	An error related to your payment method.	Fix first
131045	Message failed due to a phone number registration error.	Fix first
131047	More than 24 hours since the recipient last replied.	Send a template
131049	Not delivered, to maintain ecosystem health. The per-recipient marketing cap.	Yes, after 24h
131050	Recipient has stopped receiving marketing messages from you.	No
131051	Unsupported message type.	No
131052	Unable to download the media the user sent.	No
131053	Unable to upload the media in your message.	Fix first
131057	WhatsApp Business Account is in maintenance mode.	Yes
131063	Marketing templates are disabled on the Cloud API for this account.	No
135000	Unknown error with the request parameters.	No

Templates, at send time

Code	What Meta says	Retry?
132000	Variable parameter count mismatch.	No
132001	Template not approved, or unavailable in the requested language.	No
132005	Translated text is too long.	No
132007	Template content violates a WhatsApp policy.	No
132012	Variable parameter values formatted incorrectly.	No
132015	Template paused due to low quality.	No
132016	Template permanently disabled due to quality.	No
132018	Issue with template parameters.	No
132068	Flow is in a blocked state.	Fix first
132069	Flow throttled: 10 messages sent in the last hour.	Yes

Templates, at creation time

Code	What Meta says	Retry?
2388019	Template limit exceeded, 250 maximum.	No
2388039	Message template status can't be changed.	No
2388040	Character limit exceeded.	No
2388047	Message header format is incorrect.	No
2388072	Message body format is incorrect.	No
2388073	Message footer format is incorrect.	No
2388293	Parameters-to-words ratio exceeds the limit.	No
2388299	Leading or trailing parameters are not allowed.	No

Registration and two-step verification

Code	What Meta says	Retry?
133000	A previous deregistration attempt failed.	Yes
133004	Server temporarily unavailable.	Yes
133005	Two-step verification PIN incorrect.	Fix first
133006	Phone number needs verification before registering.	Fix first
133008	Too many two-step PIN guesses.	Yes, later
133009	Two-step verification PIN entered too quickly.	Yes, later
133010	Phone number is not registered.	Fix first
133015	Phone recently deleted; deletion not yet complete.	Yes, later
134011	WhatsApp Payments terms acceptance pending.	Fix first

Phone number migration

Code	What Meta says	Retry?
2388012	Phone number already exists in the account.	No
2388091	Phone not eligible for a verification code.	Fix first
2388093	Phone not eligible for a verification code.	Fix first
2388103	Cannot migrate the phone number.	Fix first
2494100	Account is in maintenance mode.	Yes

Template insights and synchronisation

Code	What Meta says	Retry?
200005	Template insights unavailable.	Unclear
200006	Cannot disable template insights.	Unclear
200007	Template insights have not been enabled.	Fix first
2593107	Exceeded the maximum synchronisation calls.	Yes, later
2593108	Synchronisation must occur within 24 hours.	Unclear

Marketing Messages API

Code	What Meta says	Retry?
100	Request included unsupported parameters, or the message must be a template message.	No
131055	Only marketing template messages are supported.	No
134100	You are only able to send marketing messages.	No
134101	Your template is still syncing.	Yes, later
134102	Check your eligibility status.	Fix first
1752041	Duplicate request.	No

Generic

Code	What Meta says	Retry?
1	Invalid request, or a possible server error.	Yes
2	Temporary failure due to downtime or overload.	Yes
33	The business phone number has been deleted.	No

Questions people ask

What does WhatsApp error 131049 mean?

131049 means Meta blocked that specific message to limit how much marketing a single recipient receives, described in its documentation as maintaining ecosystem health. It is temporary. Wait at least 24 hours before trying that recipient again.

What does WhatsApp error 131026 mean?

131026 means the message could not be delivered because the recipient is not able to receive it: the number is not on WhatsApp, is running a version too old to display the message, or the message was rejected on policy grounds. It is permanent and must never be retried.

What is the difference between 131049 and 131026?

131049 is temporary and caused by a per-recipient marketing cap, so retrying later is correct. 131026 is permanent and caused by the recipient being unable to receive the message at all, so retrying wastes quota and damages your quality rating. Treating the two identically is the most common and most expensive mistake in a WhatsApp send pipeline.

What does WhatsApp error 130429 mean?

130429 means you exceeded the Cloud API message throughput for your account. It is a rate limit, not a delivery failure. Reduce your send rate and retry.

What does WhatsApp error 132001 mean?

132001 means the template does not exist in the language you requested, or it has not been approved. Check both the template name and the exact language locale, since requesting en when the template is approved as en_US produces this error.

Why do WhatsApp errors not appear in the API response?

Because the send endpoint returns 200 with a message ID as soon as Meta accepts the request. Delivery is decided afterwards and reported over the status webhook, keyed to that message ID. If you do not store the returned wamid and subscribe to status webhooks, failures never reach you.

What is error code 131021 on Meta?

131021 means the sender and recipient phone numbers are the same. It is a data problem rather than a delivery problem, usually a row where the business's own number ended up in the recipient field. Do not retry it; correct the record.

What is error code 131031 on Meta?

131031 means your account has been restricted, or data verification failed. It is an integrity error, not a transient one, so retrying will not help. Check your account status in WhatsApp Manager and complete any verification Meta is asking for.

What is error code 131042 in Meta?

131042 is an error related to your payment method. Sending stays blocked until billing is fixed, so it is not something a retry queue can clear. Check the payment method attached to the WhatsApp Business Account in Meta Business Manager.

What is error code 131053 on Meta?

131053 means Meta was unable to upload the media in your message, most often because the file type is not supported. Verify the MIME type against Meta's supported media formats before retrying, since the same file will fail again unchanged.

What is error code 131000 on Meta?

131000 means the message failed to send due to an unknown error. Unlike most failures it carries no diagnosis, so it is worth one retry. If the same message fails repeatedly with 131000, the cause is usually something specific to that recipient or payload rather than a transient fault.

Stop losing leads to the follow-up gap

Kredoo captures leads from Meta and Google Ads, then follows up on WhatsApp automatically. Live in 5 minutes.

Get Started