Error Handling & Codes

How to handle WhatsApp Cloud API errors and what the common codes mean — 190 (token expired), 131030 (test recipient missing), 131047 (24-hour window closed), 131049 (per-user marketing limit), 131026 (undeliverable), 131031 (account locked), 131037 (display name not approved), 131042 (payment method), 131056 (pair rate limit), 132000/132001/132012/132015 (template errors), 368, 130429.

On this page

Where errors come from
Common error codes
More codes you'll meet
Handling errors in code
Frequently asked
Gotchas & common mistakes

When your server calls the WhatsApp Messages API and something is wrong, Meta returns an error object with a code and message. Knowing what each code means lets you fix the issue immediately.

Where errors come from#

Type 1 — API error (your call to Meta fails):

json

{ "error": { "code": 190, "message": "Invalid OAuth access token" } }

Type 2 — Status webhook failure (Meta can't deliver):

json

{ "statuses": [{ "status": "failed",
    "errors": [{ "code": 131026, "title": "Message Undeliverable" }] }] }

Common error codes#

Code	Meaning	Fix
`190`	Access token expired or invalid	Generate a new token in Meta Dashboard
`100`	Invalid parameter — the request has an unsupported or misspelled parameter	Check the endpoint's parameters; for the `to` field, check phone format (no +, include country code: `919959623255`)
`131030`	Number not in test recipients	Add the number in Meta Dashboard → API Setup
`131047`	24-hour window closed — more than 24 hours since the user last replied	Send a template message instead of free text
`131049`	Not delivered "to maintain healthy ecosystem engagement" — usually the per-user marketing template limit	Wait at least 24 hours before resending that template to that user; retrying sooner just fails again
`131026`	Message undeliverable — the number may not be on WhatsApp, the user hasn't accepted the latest Terms of Service, or their WhatsApp app is too old	Ask the user (outside WhatsApp) to check they can message your number, accept the latest terms, and update WhatsApp

More codes you'll meet#

Code	Meaning	Fix
`368`	The WhatsApp Business Account was restricted or disabled for a policy violation	Read Meta's policy enforcement guidance to see the violation and how to resolve it
`130429`	Cloud API throughput limit reached	Slow down and retry later
`131031`	Business Account locked — restricted/disabled for a policy violation, or data in the request didn't match the account (e.g. wrong two-step verification PIN)	Check the account's health status and policy notices; re-check the PIN or data you sent
`131037`	A 555 business phone number has no approved display name	Set or change the display name and wait for approval
`131042`	Problem with the payment method	Fix billing: attach a payment method / credit line, check it isn't over its limit, and set timezone and currency
`131050`	The user has stopped marketing messages from your business	Don't retry; subscribe to the `user_preferences` webhook to know when they opt back in
`131051`	Unsupported message type	Send one of the supported message types
`131056`	Too many messages from your number to the same recipient in a short time (pair rate limit)	Wait before messaging that same number again; other recipients are unaffected
`132000`	Number of template parameter values doesn't match the number of variables in the template	Send exactly one value for each variable the template defines
`132001`	Template doesn't exist in that language, or isn't approved	Check the template name, language code, and approval status
`132012`	Template parameter values are in the wrong format	Match the parameter format the template defines
`132015`	Template paused for low quality	Edit the template to improve it; send again once it's re-approved
`132016`	Template paused too many times and now permanently disabled	Create a new template with different content
`133010`	Phone number not registered on the WhatsApp Business Platform	Register the number, then retry

Handling errors in code#

try {
  await sendTextMessage(to, text);
} catch (error) {
  const code = error.response?.data?.error?.code;

  const hints = {
    190:    'Token expired — generate a new one.',
    131047: '24h window closed — use a template.',
    131049: 'Per-user marketing limit — wait 24h before resending.',
    131026: 'Undeliverable — not on WhatsApp, old app, or terms not accepted.',
    132000: 'Template parameter count mismatch.',
    131042: 'Payment method problem — fix billing.',
    131030: 'Add number as test recipient in Meta.',
  };

  console.error(`[ERROR] code: ${code} | ${hints[code] || 'check Meta docs'}`);
}

Frequently asked#

I'm getting error 190 — what do I do?

Your access token has expired or is invalid. Go to Meta Dashboard → WhatsApp → API Setup and generate a new temporary token, or create a permanent System User token. See Access tokens.

I'm getting error 131047 — what does it mean?

The 24-hour customer service window is closed. The customer hasn't messaged you in the last 24 hours. You must send a pre-approved template instead of a free-form text message.

I'm getting error 131030 — how do I fix it?

You're using a test number and the recipient's phone number isn't in your test recipient list. Go to Meta Dashboard → WhatsApp → API Setup → add the number under "To".

Error 131049 — what is this?

WhatsApp didn't deliver a marketing message because that user has already received too many marketing messages from businesses recently ("to maintain healthy ecosystem engagement"). This is a per-user cap Meta enforces, based on how that person engages with marketing messages. You cannot override it. Wait at least 24 hours before resending to that user — repeated retries within 24 hours keep failing. Marketing templates sent while the user has an open customer service window with you don't count toward the cap. Utility templates are not marketing templates, so they aren't subject to this per-user marketing limit. See Per-user marketing limit for the full rules.

Error 131026 — what does it mean?

Meta couldn't deliver the message. Common reasons: the number isn't on WhatsApp, the user hasn't accepted WhatsApp's latest Terms of Service, or they're on a very old WhatsApp version. Reach the user another way and ask them to confirm they can message your number, accept the latest terms, and update the app.

Error 132000 — number of parameters doesn't match?

The template has a different number of variables than the parameter values you sent. If the template body has {{1}} and {{2}}, send exactly two body parameters — no more, no fewer.

Error 131031 — Business Account locked?

Either the WhatsApp Business Account was restricted or disabled for a policy violation, or something in your request didn't match the account (for example an incorrect two-step verification PIN). Check the account's policy notices and health status in WhatsApp Manager, and re-check the data you sent.

Gotchas & common mistakes#

Was this page helpful?

Still stuck? Open a support ticket and our team will help.