Developer ToolsFree referencePDF, Excel, Word export

WhatsApp Cloud API Error Codes Reference

When a WhatsApp Cloud API send fails, the response carries a numeric code that tells you whether to fix your request, wait, or change how you message. This table lets you look up the common codes and get the first thing to check.

Download:

Code	Meaning	Area	First thing to check
0	AuthException: could not authenticate the app user	Auth	Regenerate the access token and confirm the app is still authorised
3	API method: capability or permissions issue	Auth	Check the app has whatsapp_business_messaging permission
10	Permission denied or removed	Auth	Check permissions granted to the system user token
100	Invalid parameter	Request	Compare the JSON body with the endpoint documentation
190	Access token expired or invalid	Auth	Replace short lived tokens with a system user token
368	Temporarily blocked for policy violations	Policy	Review the account quality and policy notices in Business Manager
80007	Rate limit issues at WhatsApp Business Account level	Throughput	Slow down and back off with jitter before retrying
130429	Cloud API throughput rate limit reached	Throughput	Queue sends and retry with exponential backoff
130472	User number is part of an experiment	Delivery	No action usually possible; retry later or use another channel
131000	Something went wrong	Server	Retry once, then raise with Meta support if it persists
131005	Access denied	Auth	Confirm the token owner is assigned to the WhatsApp Business Account
131008	Required parameter is missing	Request	Check the error details field for the missing parameter name
131009	Parameter value is not valid	Request	Check phone number format (digits with country code) and field types
131016	Service unavailable	Server	Check the Meta status page and retry later
131021	Recipient cannot be sender	Request	Do not send to the business phone number itself
131026	Message undeliverable	Delivery	Recipient may not be on WhatsApp, may have an old app version or has not accepted the terms
131030	Recipient phone number not in allowed list	Setup	Add the number to the test recipient list or move the app to live mode
131031	Account has been locked	Policy	Check for a verification or policy lock in Business Manager
131042	Business eligibility payment issue	Billing	Check the payment method and credit line on the account
131045	Incorrect certificate	Setup	Check phone number registration state and certificate
131047	Re-engagement message: more than 24 hours since the customer last replied	Window	Send an approved template message instead of a free form message
131048	Spam rate limit hit	Quality	Reduce unwanted messages; review block and report rates
131049	Message not delivered to maintain healthy ecosystem engagement	Quality	Check opt-in quality and message relevance for marketing sends
131051	Unsupported message type	Request	Check the type field against supported message types
131052	Media download error	Media	Check the inbound media ID and download it promptly with the token
131053	Media upload error	Media	Check the file type, size limit and MIME type
131056	Pair rate limit hit: too many messages to the same user in a short time	Throughput	Space out messages to one recipient and retry later
131057	Account in maintenance mode	Server	Retry after a short wait
132000	Template parameter count does not match	Template	Count the {{n}} variables in the approved template and match them
132001	Template does not exist in the language and locale	Template	Check the template name and the exact language code
132005	Translated text too long	Template	Shorten the variable values or the translation
132007	Template format character policy violated	Template	Review the template content against the messaging policy
132012	Template parameter format mismatch	Template	Check the parameter type (text, currency, date_time, media) against the template
132015	Template is paused	Template	Review quality rating and edit or replace the template
132016	Template is disabled	Template	Create a new template; disabled templates cannot be sent
133000	Previous deregistration attempt failed	Setup	Retry the deregister call before registering again
133004	Server temporarily unavailable	Server	Retry later
133005	Two step verification PIN mismatch	Setup	Check the six digit PIN used at registration
133006	Phone number needs to be verified before registering	Setup	Request and submit a verification code first
133010	Phone number not registered on the WhatsApp Business Platform	Setup	Call the register endpoint for the phone number ID

Codes and wording are summarised from Meta public documentation and can change. Always read the full error object (code, subcode, message, error_data.details) in the actual response, and confirm against the current Meta error code page.

Automate error triage

Optional review of how your ERP handles failed messaging calls and retries.

Optional. The tool and every export work without this. No spam.

How to use this reference

Search by code or by a word from the message text. Log the full error object on every failed send, not just the HTTP status, because several different problems share a 400 response. Use the Area column to decide who owns the fix: request errors are for the developer, setup and billing errors are for the account owner, and quality or policy errors are for whoever runs the messaging programme.

Request and Template errors are deterministic: fix the payload, do not retry blindly.
Throughput and Server errors are transient: retry with exponential backoff and jitter.
Window errors mean you must use an approved template, not free form text.
Quality and Policy errors need a human review of opt-in and content.

Why the error classes matter for retry logic

A retry loop that treats every failure the same either hammers a rate limit or retries a permanent error forever. Classify the code first. A 132001 will fail on every retry until the template name or language is corrected. A 130429 will usually succeed once load drops. A 131047 should switch the send path from a session message to a template message and, if your design allows, create a record that the customer window has closed.

Example: ERP shipment notification fails

An ERP posts a shipment confirmation to a customer, and the call returns 131047. The customer last wrote three days ago, so the 24 hour customer service window is closed. The fix is to send a utility template such as a shipment update with the order number and tracking link as variables. If it returns 132000 instead, the template has two variables and the code sent three, so check the mapping between ERP fields and template parameters.

Common mistakes

Teams often log only the message string, which is vague, and lose the numeric code that identifies the problem. Others hardcode a language such as en when the template was approved as en_US. Another frequent error is using a short lived token from the developer console in production, which then fails with 190 on a weekend.

Frequently Asked Questions

What does WhatsApp error 131047 mean?

It means you tried to send a free form message to a customer who has not messaged you in the last 24 hours. Outside that window only approved template messages are allowed, so resend using a template that fits the purpose.

How do I fix error 132000 on a template?

The number of parameters in your request does not match the variables in the approved template. Count the numbered placeholders in the template body, header and buttons, then send exactly that many components in the right order.

Is error 130429 a permanent failure?

No. It signals that you reached the Cloud API throughput limit for your number. Queue outgoing messages, retry with exponential backoff and jitter, and smooth bulk sends so they do not arrive in one burst.

Are these codes the complete list?

No. This is a working subset of frequently seen codes. Meta adds and changes codes over time, so treat the live documentation and the error details in your own responses as the authority.

If you want failed messaging calls from your ERP triaged and retried by class automatically, Netray can build that into your integration layer.

Talk to an Expert Explore More Free Tools

Related Tools

ERP Operations

More Developer Tools tools

See all

Back to All Tools