WhatsApp Cloud API Error Codes Explained

When a WhatsApp message fails, Meta returns a numeric error code. The code tells you whether to fix your request, fix your account, wait, or give up on that recipient. Retrying everything the same way wastes your messaging limit and can hurt your quality rating, so it pays to know which group a failure falls into.

This guide covers the codes you're most likely to see when sending. Every meaning here comes from Meta's official error code reference as of November 2026. Meta adds and rewords codes over time, so check that page when you hit something not listed here.

Where errors show up

Meta says Cloud API errors can arrive in three ways:

• Synchronously, in the Graph API response to your send request. This is typical for bad parameters or token problems.
• Asynchronously, through the messages webhook, after the request was accepted. Delivery failures usually arrive this way.
• Both.

So a 200 response to your send call doesn't mean the message was delivered. Log the error code and details from both places against the message ID, or you'll end up with campaigns that look "sent" but never arrived.

Authorization and account errors

Code	Meaning	What to do
0	Couldn't authenticate the app user. The token may be expired or invalidated	Generate a new token
3	Capability or permissions issue	Check the token's permissions in the Access Token Debugger
10	Permission not granted or removed	Same as above. Also check the API's eligibility requirements
190	Access token expired	Get a new token. For servers, use a system user token
131005	Permission not granted or removed	Verify the token has whatsapp_business_messaging and whatsapp_business_management
368	Account restricted or disabled for a policy violation	Read Meta's policy enforcement documentation. Retrying won't help
131031	Account restricted, either for a policy violation or because submitted data didn't match the account (for example a wrong two-step PIN)	Check the account in WhatsApp Manager and consider the Health Status API

Request and parameter errors

These mean your request is wrong. Fix the payload; resending the same request will fail the same way.

Code	Meaning
100	Unsupported or misspelled parameter, or a value over a length limit
131008	Required parameter missing
131009	One or more parameter values are invalid
131021	Sender and recipient are the same number
131051	Unsupported message type
131053	Media upload failed, often because the MIME type isn't supported
135000	Generic error with the request parameters. Check the syntax

Recipient and delivery errors

These are about the person you're messaging, not your code.

Code	Meaning	What to do
131026	Message undeliverable. Causes include a number that isn't on WhatsApp, a recipient who hasn't accepted the latest terms, or an outdated WhatsApp version	Confirm the number. Don't retry in a loop
131047	More than 24 hours have passed since the recipient last replied	Send an approved template instead of free-form text
131049	Not delivered "to maintain healthy ecosystem engagement"	Meta advises waiting at least 24 hours before resending the template. Don't hammer the same person
131050	Recipient has stopped receiving marketing messages	Don't retry. Meta suggests subscribing to the user_preferences webhook to keep your list in sync
131052	Couldn't download media the user sent you	Check error.error_data.details and ask the user to resend
130472	Not sent as part of a Meta marketing message experiment	See Meta's marketing message experiment docs

131047 is the one most teams hit first. It isn't a bug: it's WhatsApp's 24-hour customer service window rule. Our guide to the 24-hour window and pricing explains it.

Throttling and rate limits

Code	Meaning	What to do
4	The app hit its API call rate limit	Slow down and retry with backoff
80007	The WhatsApp Business Account hit its rate limit	Same
130429	Cloud API message throughput reached	Retry later or send at a lower rate
131056	Too many messages from one sender to the same recipient in a short time	Wait before messaging that person again. Other recipients aren't affected
133016	Too many register/deregister attempts on one number	Wait. Meta allows 10 per 72 hours

These are the codes where retrying makes sense, but with exponential backoff and a cap, not instantly.

Template errors (132000 series)

Code	Meaning	What to do
132000	Number of parameter values doesn't match the template	Send exactly one value per {{n}}
132001	Template doesn't exist in that language, isn't approved, or the name/locale is wrong	Check the name and language code match an approved template
132005	Translated text too long	Check the translation in WhatsApp Manager
132007	Template content violates a WhatsApp policy	Review the template review rules
132012	Parameter values formatted incorrectly	Match the format the template defines for each parameter
132015	Template paused for low quality	Edit it and send again once it's approved
132016	Template paused too many times; permanently disabled	Create a new template with different content

If templates are being rejected before you even get to send them, see why WhatsApp templates get rejected.

Account and number state errors

Code	Meaning
131000	Unknown error. Retry; if it persists, open a Direct Support ticket
131016	A service is temporarily unavailable. Check the WhatsApp status page
131037	The 555 business number has no approved display name
131042	Payment method problem: check billing setup, credit line, time zone and currency
131045	Phone number registration error. Register it first
131048	Sending restricted because many messages were blocked or flagged as spam. Check quality in WhatsApp Manager
131057	Account in maintenance mode, for example during a throughput upgrade
133010	Phone number not registered

131042 is worth watching. Meta now charges for service messages too (see the pricing article), so a missing payment method affects more of your traffic than it used to.

A simple retry policy

Sort failures into three buckets:

Retry with backoff:   4, 80007, 130429, 131016, 131000 (limited attempts)
Wait before resending: 131049 (24 h), 131056 (same recipient)
Do not retry, fix:    0, 3, 10, 100, 131005, 131008, 131009, 131051,
                      132000, 132001, 132005, 132007, 132012, 133010
Do not retry, drop:   131026 (verify number), 131050 (opted out)
Escalate:             368, 131031, 131042, 131048, 132015, 132016

The rest is bookkeeping: store the raw code and message with each failed recipient so whoever reads the report can act on it.

Seeing these codes in campaign reports

A "12 failed" count with no detail isn't something anyone can act on. In Mesvilo, campaign reports show sent, delivered, read and failed counts, and every failure keeps Meta's original error code and response, exportable as CSV. That makes it easy to separate 131050 opt-outs from 131026 bad numbers before the next send.

You can open a sample campaign report in the live demo or see the full feature list on the product page.

Sources

• WhatsApp error codes
• Register a business phone number
• Service messages and customer service windows