WhatsApp API Error Codes: What Each One Means

Your logs say (#131049) This message was not delivered to maintain healthy ecosystem engagement. The on-call question is simple: retry, fix something, or give up on this recipient? The answer depends entirely on the number in brackets, and guessing wrong either spams a customer or silently drops a message.

This is a working reference to WhatsApp API error codes on Meta's Cloud API: how errors reach you, what the codes you'll actually see mean, and what to do about each. Every code and description below was checked against Meta's error codes page as of October 2026; we left out codes we couldn't confirm there.

It ends with a small function that turns a code into a next step, so your sender handles errors the same way every time. For the platform overview, see our complete guide to the WhatsApp API.

How Cloud API errors reach you

Errors come back in two places, and sometimes both. A request that's invalid fails synchronously: the HTTP response carries an error object. A problem discovered later, such as a user who can't receive messages, arrives asynchronously in a failed status webhook. Meta recommends watching both.

The synchronous shape, using Meta's own example:

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput has been reached."
    },
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

In webhooks, the same information appears as an errors array on a status (statuses[].errors), on an incoming message of type unsupported, or at the top level of value for system and account problems.

Four rules from Meta's documentation:

• Branch on code and read details. Titles inside message will eventually be deprecated, so don't string-match them.
• Ignore error_subcode. It's deprecated and not returned from v16.0 onward.
• Log fbtrace_id. Meta support asks for it.
• Expect different codes for the same request. Meta runs its validation checks in an order that can change, so a request with two problems may report either one first.

Token and permission errors

These mean the request never got as far as WhatsApp. Retrying won't help until the token is fixed. Paste the token into Meta's Access Token Debugger and check it has whatsapp_business_messaging and whatsapp_business_management.

Throttling errors

Throttling errors are the ones you should retry, with care. Retrying instantly in a tight loop turns a rate limit into an outage.

Our throughput guide covers queueing and the automatic upgrade to 1,000 messages per second.

Message delivery errors

These are the codes behind most "why didn't it arrive?" tickets.

Some of these, 131049 among them, are reported on a failed status webhook rather than in the HTTP response, which is why you watch both. Our undelivered message checklist walks through diagnosing them in order.

Account, template and registration errors

Account and integrity. 368 means the account was restricted or disabled for a policy violation. 130497 means it can't message users in certain countries. 131031 means the account is restricted or disabled, or request data such as a two-step verification PIN didn't match; Meta points to the Health Status API for details. 131042 is a billing problem, such as no payment method attached, a credit line over its limit, or timezone or currency not set. 131045 means the number isn't registered, 131037 means a Meta-provided 555 business number has no approved display name, and 33 means the phone number was deleted.

Template sends. These usually mean your code and the template disagree:

Template creation. 2388040 is a field over its character limit; 2388047, 2388072 and 2388073 are header, body and footer formatting problems; 2388293 means too many variables for the text length; 2388299 means a variable sits at the very start or end. 2388019 means you've hit the template cap, which Meta sets at 250 per account for unverified portfolios and up to 6,000 for verified ones with an approved display name. For rewrite examples, see why WhatsApp templates get rejected.

Registration. 133005 is a wrong two-step PIN, 133008 and 133009 mean too many or too fast PIN attempts, 133006 means verify the number before registering, 133010 means it isn't registered, 133000 means a previous deregistration failed, and 133015 means a recently deleted number is still being removed; wait 5 minutes.

Turn codes into actions

Don't scatter error handling across your codebase. One function that maps a code to a next step keeps every sender consistent:

const RETRY_WITH_BACKOFF = new Set([2, 4, 80007, 130429, 131000, 131016, 131057, 133004]);
const FIX_THE_REQUEST = new Set([100, 131008, 131009, 131051, 131053, 132000, 132001, 132005, 132012]);
const FIX_THE_TOKEN = new Set([0, 3, 10, 190, 131005]);
const DO_NOT_RETRY = new Set([130403, 131021, 131026, 131050]);

export function nextStep(code) {
  if (code === 131047) return "send_template";      // window closed
  if (code === 131049) return "wait_24h";           // per-user marketing limit
  if (code === 131056) return "slow_down_for_user"; // pair rate limit
  if (RETRY_WITH_BACKOFF.has(code)) return "retry_with_backoff";
  if (FIX_THE_TOKEN.has(code) || (code >= 200 && code <= 299)) return "fix_token";
  if (FIX_THE_REQUEST.has(code)) return "fix_request";
  if (DO_NOT_RETRY.has(code)) return "do_not_retry";
  return "alert_a_human"; // 368, 131042, 131048, 132015 and anything unknown
}

Three habits make this pay off. Cap retries and add jitter so a throughput error doesn't become a thundering herd. Mark do_not_retry recipients in your CRM so the next campaign skips them. And page a person for alert_a_human codes, because account restrictions, billing failures and paused templates stop every send, not just one.

If a message returns no error at all but never arrives, work through our checklist for WhatsApp API messages not delivered.

Where Tenashi fits

Many of these errors exist because of the official platform's rules: templates, windows, marketing limits, billing. If your WhatsApp traffic is mostly conversations with people who already know your business, Tenashi's API avoids that whole class. It sends from the number your team already uses, linked by QR scan, with no templates, no window and no per-message fees, from $18/mo with the API included.

It has its own small set of errors, all in one shape with string codes you can branch on: invalid_phone, unauthorized, plan_required, number_disconnected, send_blocked (ban protection paused a repeated text), rate_limited, new_chat_limit and media_too_large. It isn't Meta's API and isn't meant for OTPs or high volume.

Read the API docs · Get started

FAQ

What does WhatsApp API error 131047 mean?

It means more than 24 hours have passed since the user last messaged your business number, so the customer service window is closed and free-form messages aren't allowed. Send an approved template instead. If the user replies, a new 24-hour window opens and you can send regular messages again.

What does WhatsApp error 131026 mean?

The message was undeliverable. Meta lists three causes: the number isn't on WhatsApp, the user hasn't accepted WhatsApp's latest terms of service, or they're on a very old app version. Retrying won't help. Contact the customer another way and ask them to check their number, accept the terms or update WhatsApp.

How should I handle error 130429?

It means your number hit its throughput limit, 80 messages per second by default. Put sends behind a queue, retry with exponential backoff and jitter, and keep concurrency below the limit. If you're consistently above it, Meta upgrades eligible numbers to 1,000 messages per second automatically, with no extra charge.

When can I resend after error 131049?

Wait at least 24 hours. The code means WhatsApp withheld the message, usually because the user hit the per-user limit on marketing messages. Meta warns that resending within 24 hours to users at their limit can block further attempts for up to a day and distorts your delivery reporting.

Why does the same request return different error codes?

Meta validates each send through several checks and may run them in a different order over time. A request with two problems can report either one first, so you may see one code, fix it, and then hit another. Branch on the code you receive and log details and fbtrace_id.

---

A clear map from code to action is most of what reliable sending is. And if template and window errors make up most of your logs, Tenashi's API docs show a send path that has neither.