WhatsApp Cloud API Error Codes Directory
Searchable reference for Meta WhatsApp Cloud API error codes. Plain language root cause explanations, Meta documentation references, and production remediation code.
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"