WhatsApp Cloud API Error Codes: The Common Ones and Fixes
Most WhatsApp Cloud API errors fall into a handful of groups: an expired or missing access token, a rate limit, a closed 24-hour window, a template problem, a recipient who can't receive the message, or a restriction on your account. The error code tells you which group you're in, and each group has its own fix. The table below covers the codes businesses hit most often, checked against Meta's developer documentation on October 22, 2026.
One rule saves a lot of time: some errors clear if you wait and retry, and others fail the same way every time until you change something. Knowing which is which stops you from looping on a message that will never send.
Where to find the error code
Meta returns errors in two places, sometimes both. Some come back straight away in the API response to your send request. Others arrive later in the messages webhook, after Meta has accepted the request but couldn't deliver it. Watch both, or you'll miss failures that only show up in the webhook.
Each error carries a few fields worth knowing:
- code: the number to build your error handling around.
- message: the code plus a short title, for example "(#130429) Rate limit hit". Meta says titles will eventually be deprecated, so don't rely on them.
- error_data.details: a plain description of what went wrong, sometimes with the fix.
- fbtrace_id: a trace ID to include if you open a case with Meta support.
The common error codes and what they mean
| Code | What it means | Fix |
|---|---|---|
| 0 | The app user couldn't be authenticated | The token expired, was invalidated, or access was revoked. Get a new token. |
| 190 | The access token has expired | Get a new access token |
| 100 | Unsupported or misspelled parameter | Check parameter names, the phone number ID and length limits |
| 4 | The app hit its API call rate limit | Retry later or make fewer calls |
| 80007 | The WhatsApp Business Account hit its rate limit | Retry later or make fewer calls |
| 130429 | Message throughput limit reached | Slow down and retry later |
| 131056 | Too many messages to the same person in a short time | Wait before messaging that person again; others aren't affected |
| 131048 | Sending from this number is restricted | Check the number's quality status in WhatsApp Manager |
| 131047 | More than 24 hours since the customer last replied | Send an approved template instead |
| 131026 | Message couldn't be delivered | Confirm the number is on WhatsApp and the app is up to date |
| 131049 | Not delivered "to maintain healthy ecosystem engagement" | Wait at least 24 hours before resending |
| 131050 | The customer stopped marketing messages from you | Don't retry |
| 132000 | Wrong number of template variables | Supply a value for every variable |
| 132001 | Template missing in that language, or not approved | Check approval, the exact name and the language code |
| 132015 | Template paused for low quality | Edit it and wait for approval |
| 131042 | A problem with your payment method | Fix billing on the WhatsApp Business Account |
| 133010 | Phone number isn't registered | Register the number, then retry |
| 368 | Account restricted or disabled for a policy violation | Follow Meta's policy enforcement steps |
| 131031 | Account restricted, or request data couldn't be verified | Find the cause, then appeal or correct your data |
| 131000 | Unknown send failure | Retry; open a support case if it keeps happening |
Meta's list is much longer, with codes for phone registration, Flows, media and the Marketing Messages API. Our help center list of error codes covers the full set. For anything not listed here, read Meta's WhatsApp error codes reference.
Errors that clear if you wait
Rate limit errors (4, 80007 and 130429) mean you're sending or calling faster than Meta allows. Pause, then retry more slowly. If your system sends in bursts, space the sends out rather than firing them all at once.
131056 is narrower. It only affects one recipient you've messaged too often in a short time, so your other messages keep going. 131000 and the temporary downtime codes (1, 2 and 131016) can also succeed on a later attempt.
131049 needs patience. Meta held back a marketing message to keep engagement healthy, and resending sooner than 24 hours will likely fail again.
Errors you have to fix first
Token errors (0, 190). Your connection lost its permission to send. Generate a new access token, or reconnect the number in the tool you use. Error 0 can also mean the user who granted access removed it, so check that too.
131047, the closed window. You can only send a free-form message within 24 hours of the customer's last message. After that, send an approved template, and continue the conversation once they reply.
Template errors (132000, 132001, 132015). These are almost always typos or mismatches. Check that the template name and language code match exactly, that it's approved, and that you're filling every variable. A paused template needs editing and new approval before it sends again.
131026, undeliverable. The recipient may not use WhatsApp, may not have accepted the latest terms, or may be on an old app version. Ask them through another channel, such as email, to update WhatsApp and message you first.
131050, opted out. The customer chose to stop marketing messages from your business. Respect it and don't retry.
131048, sending restricted. Too many of your messages were blocked or flagged. Open WhatsApp Manager, check the number's quality rating, and send less to fewer, better-targeted people who opted in. Sending more won't fix it.
131042, billing. Meta can't charge you. Check that a payment method is attached to the WhatsApp Business Account, that it hasn't hit its credit line, and that the account isn't suspended.
Account-level errors: 368 and 131031
These two are the serious ones, because they block every send on the account, not just one message. Error 368 means the account was restricted or disabled for breaking a Meta policy. Error 131031 means the account is locked, either for a policy violation or because Meta couldn't verify data in the request, such as a wrong two-step verification PIN.
Retrying won't help either one. Check WhatsApp Manager and Meta Business Suite for notices, then appeal a policy restriction or correct your business details. We cover the four causes of 131031 and how to clear each in our guide to WhatsApp error 131031. To keep this from happening in the first place, read how to avoid getting your number banned.
A simple way to handle errors
- Log the code, the details text and the fbtrace_id for every failure.
- Retry only the temporary codes, with a growing pause between attempts.
- Never retry 131050, 131049 within 24 hours, or the account-level codes.
- Send 131047 failures to a template step instead.
- Alert a person when you see 131048, 368 or 131031, because the whole number is at risk.
Frequently asked questions
Where do WhatsApp API error codes show up?
Some come back immediately in the API response to your send request. Others arrive later in the messages webhook. Monitor both, or you'll miss failed deliveries.
What does error 131047 mean?
More than 24 hours have passed since the customer last messaged you, so you can't send a free-form message. Send an approved template instead.
Which WhatsApp API errors are safe to retry?
Rate limit errors such as 4, 80007, 130429 and 131056, plus unknown or temporary errors such as 131000, can succeed later. Wait between attempts. Don't retry opt-outs, closed-window errors or account restrictions.
What is the difference between error 368 and 131031?
Both block sending for the whole account. 368 means a policy restriction. 131031 can be a policy restriction or data Meta couldn't verify, such as a wrong two-step verification PIN.
Try HaberChat free for 7 days
No credit card needed. Connect your number through the Cloud API, coexistence or a QR code, and get help from a team that reads these errors every day. Start your free trial or compare plans.
