WhatsApp Cloud API Error Codes Directory
Last verified: · Reviewed quarterly · Meta error code reference ↗
Most WhatsApp Cloud API errors are permanent for that message: change the request rather than retrying it. Three are not. 130429, 131048 and 131056 are throughput caps that Meta returns as HTTP 400 rather than 429, so the standard “do not retry a 4xx” rule fails them permanently even though the cap clears on its own. This page lists what each code means and, unusually, what to do with it.
Searchable reference for Meta WhatsApp Cloud API error codes: plain language root causes, Meta documentation references, production remediation code, and an open dataset of the handling decision each code implies.
Free dataset: error codes with retry semantics
Every code we document, as JSON, licensed CC-BY. Every vendor lists what a code means. This also records what to do with it: retry, fail, suppress the contact, switch to a template, or raise an account alert. 130429, 131048 and 131056 are throughput caps that Meta returns as HTTP 4xx, not 429 — a generic "4xx is not retryable" rule fails them permanently. The flags are generated from the same classifier our live send path uses.
Codes worth their own page
Most references tell you what a code means. These cover what to do with it: whether to retry, suppress the contact, switch to a template, or raise an account alert. Ordered by how often they actually occur.
Optionally Capped / Messaging Limit Reached
Root Cause: Your WhatsApp Business Account (WABA) has exceeded its 24-hour unique recipient tier capacity (e.g., 1,000 unique customers per 24 hours for Tier 1). Outbound messages to new recipients are rejected until the 24-hour rolling window resets or your tier upgrades.
// Klaros Auto-Retry & Capped Queue Handling
if (error.code === 131030) {
// Queue message for staggered retry after rolling 24h window reset
await env.CAMPAIGN_QUEUE.send({ payload, retryAt: Date.now() + (3600 * 1000) });
}
Re-engagement Window Expired (24-Hour Gate)
Root Cause: More than 24 hours have elapsed since the customer's last inbound message. Free-form text or media messages cannot be delivered outside the 24-hour service window.
// Remediation: Fallback to Approved Utility/Marketing Template
if (error.code === 131047) {
return await sendWhatsAppTemplate({ to: recipient, template: "reengage_notification" });
}
Unsupported Message Type
Root Cause: The message payload format or media type is not supported by the Meta Graph API v25.0 endpoint.
// Ensure valid message type schema
const validTypes = ["text", "template", "interactive", "image", "document", "audio", "video", "location"];
if (!validTypes.includes(payload.type)) throw new Error("Invalid Meta payload type");
Template Does Not Exist or Language Mismatch
Root Cause: The requested template name or language code (e.g. `en_US` vs `en`) does not exist or is not approved in your WABA.
// Check template status before campaign dispatch
const template = await getTemplateByName(db, templateName, languageCode);
if (!template || template.status !== "APPROVED") {
throw new Error(`Template ${templateName} (${languageCode}) is not approved`);
}
Invalid Parameter / Expired Access Token
Root Cause: The Meta System User access token passed in the `Authorization: Bearer` header has expired or lacks the `whatsapp_business_messaging` permission.
// Verify Bearer Token validity curl -X GET "https://graph.facebook.com/v25.0/debug_token?input_token=YOUR_ACCESS_TOKEN" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Deeper reading on WhatsApp API failure modes
Production post-mortems for the errors developers hit most.
The broadcast that lost its tail
130429 throughput cap arrives as HTTP 4xx. How to classify and queue retries correctly.
Engineering NoteThe session that logged itself out
How Chromium process leaks force a QR loop — and why Cloud API eliminates this class of error.
Engineering NoteThe auto-reply that could loop forever
Auto-responders replying to broadcast acknowledgements: the suppression logic that stops it.
Engineering NoteSilent enrichment failure
A contact enrichment pipeline that failed without raising an error — and how to detect it.