Skip to content

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

CodeWhat it meansFix
0The app user couldn't be authenticatedThe token expired, was invalidated, or access was revoked. Get a new token.
190The access token has expiredGet a new access token
100Unsupported or misspelled parameterCheck parameter names, the phone number ID and length limits
4The app hit its API call rate limitRetry later or make fewer calls
80007The WhatsApp Business Account hit its rate limitRetry later or make fewer calls
130429Message throughput limit reachedSlow down and retry later
131056Too many messages to the same person in a short timeWait before messaging that person again; others aren't affected
131048Sending from this number is restrictedCheck the number's quality status in WhatsApp Manager
131047More than 24 hours since the customer last repliedSend an approved template instead
131026Message couldn't be deliveredConfirm the number is on WhatsApp and the app is up to date
131049Not delivered "to maintain healthy ecosystem engagement"Wait at least 24 hours before resending
131050The customer stopped marketing messages from youDon't retry
132000Wrong number of template variablesSupply a value for every variable
132001Template missing in that language, or not approvedCheck approval, the exact name and the language code
132015Template paused for low qualityEdit it and wait for approval
131042A problem with your payment methodFix billing on the WhatsApp Business Account
133010Phone number isn't registeredRegister the number, then retry
368Account restricted or disabled for a policy violationFollow Meta's policy enforcement steps
131031Account restricted, or request data couldn't be verifiedFind the cause, then appeal or correct your data
131000Unknown send failureRetry; 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

  1. Log the code, the details text and the fbtrace_id for every failure.
  2. Retry only the temporary codes, with a growing pause between attempts.
  3. Never retry 131050, 131049 within 24 hours, or the account-level codes.
  4. Send 131047 failures to a template step instead.
  5. 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.