WhatsApp Cloud API Error Codes: Full List, Fixes & Examples

This is a developer reference for WhatsApp Cloud API error codes: what each code means, whether to retry it, and how to fix it, with example payloads. Codes and definitions were last checked against Meta's official error code reference on 30 October 2026. Meta adds and changes codes over time, so treat their page as the final word.

Want our team to fix the error for you? If you're a Get Click Media customer, or you'd like your WhatsApp API issues monitored and fixed for you, see our WhatsApp API error support page.

Where Errors Appear

Errors reach you in one of two places, and you need to handle both:

1. The API response. When the request itself is rejected, you get an error before the message is accepted, for example an invalid parameter or a missing permission.
2. A failed status webhook. The request was accepted, and you received a wamid, but the message failed later, for example because it was undeliverable or blocked by a policy limit. These failures never appear in the API response.

Meta notes that Cloud API runs its checks in no fixed order, so a request with several problems can return a different code from one attempt to the next. Fix the reported problem, resend, and check again.

Example: synchronous API error

{
  "error": {
    "message": "(#132001) Template name does not exist in the translation",
    "type": "OAuthException",
    "code": 132001,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "template name (order_confirm) does not exist in en_US"
    },
    "fbtrace_id": "A1b2C3d4E5f6"
  }
}

Read error.code to decide what to do, and error_data.details to see exactly what failed. Log fbtrace_id, because Meta support asks for it.

Example: asynchronous failed status

{
  "statuses": [{
    "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS...",
    "status": "failed",
    "timestamp": "1761810000",
    "recipient_id": "919876543210",
    "errors": [{
      "code": 131026,
      "title": "Message undeliverable",
      "message": "Message undeliverable",
      "error_data": { "details": "Message Undeliverable." }
    }]
  }]
}

Error Code Reference

Retry? column: Yes = retry with exponential backoff. Later = wait for the limit or window to reset, then retry. No = change the request, account, or recipient first.

Authorization and permissions

Code	Meaning	Retry?	Fix
0	AuthException- could not authenticate	No	Check the token is complete and sent as Authorization: Bearer <token>
3	API method- capability or permission issue	No	Check the app has the WhatsApp product and the needed permissions
10	Permission denied	No	Check that the token has whatsapp_business_messaging / whatsapp_business_management, and that the System User is assigned to the WABA
190	Access token expired or invalid	No	Generate a new token. Use a System User token with no expiry in production, not the 24-hour temporary token
200–299	API permission error	No	Grant the missing permission, then generate a new token
131005	Access denied- permission not granted or removed	No	Check the token in the Access Token Debugger, then regenerate it with the right permissions

Throughput and limits

Code	Meaning	Retry?	Fix
4	Too many API calls (app-level)	Later	Reduce the call rate, for example by batching reads and caching template lookups
80007	WhatsApp Business Account rate limit reached	Later	Spread calls out. See rate limits
130429	Throughput reached- sending faster than this number's messages-per-second limit	Yes	Pace sends below the number's limit (80 msg/sec by default) and back off exponentially
131048	Spam rate limit- sending restricted because of quality	Later	Check the number's quality rating in WhatsApp Manager. Pause campaigns and improve targeting
131049	Not delivered to maintain healthy ecosystem engagement (per-user marketing limit)	Later	Don't retry for at least 24 hours. Send fewer marketing messages to this user
131056	Pair rate limit- too many messages to the same user	Yes	Wait before messaging this user again. Other recipients are unaffected

Recipient and delivery

Code	Meaning	Retry?	Fix
131021	Recipient is the same as the sender	No	Send to a different number
131026	Message undeliverable	No	The recipient may not be on WhatsApp, may not have accepted the latest Terms, or may be on an old app version. Fall back to SMS or another channel
131030	Recipient not in the allowed list	No	Only applies to test numbers. Add the recipient in the App Dashboard, or send from a production number
131047	Re-engagement message- more than 24 hours since the user last replied	No	Send an approved template instead of free-form content
131050	User has stopped marketing messages from you	No	Suppress marketing to this user. Don't retry
131051	Unsupported message type	No	Check type is a supported message type and the payload matches it

Template errors

Code	Meaning	Retry?	Fix
132000	Number of parameters doesn't match the template	No	Send exactly as many parameters as the template has placeholders, for each component
132001	Template does not exist (in that language)	No	Check the exact name, the exact language code (en vs en_US) and that the status is APPROVED
132005	Text too long after parameters are filled in	No	Shorten the parameter values
132007	Template content breaks a formatting policy	No	Remove disallowed characters, such as newlines, tabs, or more than 4 consecutive spaces, from parameter values
132012	Parameter format doesn't match	No	Match the parameter type to the template, for example image for an image header, currency or date_time where defined
132015	Template paused for low quality	Later	Edit the template or wait for Meta to unpause it. Use a different template in the meantime
132016	Template permanently disabled	No	Create a new template with improved content

Media

Code	Meaning	Retry?	Fix
131052	Media download error- couldn't download media the user sent	Yes	Ask the user to resend. Check the media ID and that your token can access it
131053	Media upload error- couldn't use the media you sent	No	Use a public HTTPS URL with the correct Content-Type, or upload to /{PHONE_NUMBER_ID}/media first and send by id. Check size and type limits

Account, number, and registration

Code	Meaning	Retry?	Fix
368	Temporarily blocked for policy violations	Later	Review the policy notice in WhatsApp Manager. Appeal if you believe it is wrong
131031	Business account locked	No	Check Business Support / WhatsApp Manager for the reason. This often needs an appeal
131042	Business eligibility- payment issue	No	Add or fix the payment method on the WABA
131045	Message failed because of a phone number registration error	No	Register the number again (see 133010)
131057	Account in maintenance mode	Later	Wait. This is often temporary during a throughput upgrade
133000	Previous deregistration was not completed	No	Deregister the number fully, then register it again
133004	Server temporarily unavailable	Yes	Retry with backoff
133005	Two-step verification PIN incorrect	No	Use the correct PIN, or reset it in WhatsApp Manager
133006	Phone number needs to be verified again	No	Verify the number again before registering
133008 / 133009	Too many PIN attempts, or attempts too fast	Later	Wait for the time given in the error, then try again
133010	Your business number is not registered on the Cloud API	No	Call POST /{PHONE_NUMBER_ID}/register
133015	Number was recently deleted. Wait before registering it	Later	Wait a few minutes, then register

General

Code	Meaning	Retry?	Fix
131000	Something went wrong (unknown error)	Yes	Retry with backoff. If it keeps happening, contact Meta support with the fbtrace_id
131008	Required parameter missing	No	Add the field named in error_data.details
131009	Parameter value invalid	No	Fix the value named in error_data.details, for example the phone number format (country code, no +)
131016	Service unavailable	Yes	Retry with backoff. Check the platform status page
HTTP 5xx	Meta server error	Yes	Retry with backoff

Worked Fixes

132000- parameter count mismatch

The template body is Hi {{1}}, your order {{2}} is confirmed., so it has two placeholders. This request sends only one parameter:

"components": [{ "type": "body",
  "parameters": [{ "type": "text", "text": "Asha" }] }]

"components": [{ "type": "body",
  "parameters": [
    { "type": "text", "text": "Asha" },
    { "type": "text", "text": "#10234" }
  ] }]

If the template has a header with a variable, or buttons with dynamic URLs, each needs its own component entry too.

132001- language code mismatch

The template was approved as en_US, but the request sends "language": { "code": "en" }. Use the language code exactly as listed on the template. Check it with GET /{WABA_ID}/message_templates?name=order_confirmation.

132007- formatting characters in parameters

Parameter values that contain newlines (\n), tabs, or more than four spaces in a row are rejected. Clean user-supplied values before sending:

const clean = (s) => String(s).replace(/[\n\t]/g, ' ').replace(/ {4,}/g, '   ').trim();

131047- outside the 24-hour window

You can only send a free-form "type": "text" reply within 24 hours of the user's last message. Track the user's last inbound message time from your webhook. After 24 hours, switch to a template:

const inWindow = Date.now() - lastInboundAt < 24 * 60 * 60 * 1000;
const payload = inWindow
  ? { type: 'text', text: { body: reply } }
  : { type: 'template', template: { name: 'follow_up', language: { code: 'en' } } };

Error Handling Pattern- Node.js

This handles both synchronous errors and the retry rules from the tables above.

const axios = require('axios');

const RETRYABLE = new Set([130429, 131000, 131016, 131052, 131056, 133004]);

async function sendWhatsApp(payload, attempt = 0) {
  try {
    const res = await axios.post(
      `https://graph.facebook.com/${process.env.API_VERSION}/${process.env.PHONE_NUMBER_ID}/messages`,
      { messaging_product: 'whatsapp', ...payload },
      { headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}` } }
    );
    return res.data.messages[0].id; // wamid- accepted, not yet delivered
  } catch (err) {
    const status = err.response?.status;
    const e = err.response?.data?.error || {};
    const retryable = RETRYABLE.has(e.code) || status >= 500;

    if (retryable && attempt < 5) {
      const delay = Math.min(2 ** attempt * 1000, 30000) + Math.random() * 500;
      await new Promise((r) => setTimeout(r, delay));
      return sendWhatsApp(payload, attempt + 1);
    }

    console.error('WhatsApp send failed', {
      code: e.code, details: e.error_data?.details, fbtrace_id: e.fbtrace_id
    });
    throw err;
  }
}

Handle errors in failed webhook statuses as well. Suppress the recipient for 131050, fall back to another channel for 131026, and wait 24 hours before trying 131049 again.

Frequently Asked Questions- WhatsApp API Error Codes

What does WhatsApp error 131047 mean? You sent a non-template message more than 24 hours after the user last messaged you. Send an approved template instead.

What does WhatsApp error 132001 mean? The template name and language combination isn't an approved template on your WABA. Check the exact name, the exact language code, and that the status is APPROVED.

What does WhatsApp error 131026 mean? WhatsApp couldn't deliver to that recipient, usually because the number isn't on WhatsApp, the user hasn't accepted the latest Terms, or they're on an old app version.

What does WhatsApp error 133010 mean? Your sending number isn't registered on the Cloud API. Register it with POST /{PHONE_NUMBER_ID}/register.

Which WhatsApp API errors should I retry? Retry only throughput and temporary errors (130429, 131016, 131000, 133004, 5xx) with exponential backoff. Fix the request first for payload, template, and policy errors.

Official References

• WhatsApp Cloud API error codes- Meta for Developers
• Errors in messages webhooks- Meta for Developers
• WhatsApp Business Platform status page

Related Guides

• WhatsApp API rate limits- throughput vs messaging limits and a step-by-step troubleshooting sequence
• WhatsApp Cloud API setup guide- tokens, number registration, and webhooks
• WhatsApp API error support- let Get Click Media's team diagnose and fix errors for you