WhatsApp API Error Codes: Troubleshooting & Solutions

It means the 24-hour customer-service window has closed since the recipient last messaged you, so a free-form session message can't be sent - you need to send an approved template instead to re-open the conversation.

It's a parameter count mismatch - the number of variables your request sends doesn't match the number of placeholders in the approved template. Check your params array against the template exactly.

Most commonly because the template isn't approved yet, or the content sent doesn't exactly match what Meta approved. See the Template Errors table on this page.

Your access token is likely missing, expired or revoked. Confirm the Authorization header is present on every request and that the token hasn't expired - see the Authentication Errors table.

An accepted request (HTTP 200) only means the API received your request - actual delivery is reported separately through status webhooks. Check the delivery status event for the real outcome, not just the initial response.

It means you're sending faster than your account's current throughput allows, or have triggered spam-protection thresholds from recipient blocks/reports. See the Rate-Limit Errors table for the specific conditions.

No. Retry transient failures, but retrying a rejected template, an invalid recipient, or a permission error will just fail again - branch on the specific error reason instead of retrying blindly.

The HTTP status (like 200, 400 or 401) reflects whether the API request itself was well-formed and authenticated. The WhatsApp-specific error code in the response body explains what actually went wrong with the messaging operation - both matter for diagnosis.

The failed status event includes a reason - commonly an unapproved template, an unreachable number, or media issues. See the Message Delivery Failures section, and Webhook Errors on WhatsApp API Webhooks for endpoint-side issues specifically.

It typically means the file you're sending exceeds a size limit or is in an unsupported format for that media type - re-encode or resize the file and retry.

Account restrictions usually follow a detected policy violation, a country-level messaging restriction, or a temporary platform maintenance state - check recent notices in your business account for the specific reason.

Idempotency means safely handling a retried request without sending a duplicate message - important because network retries after a timeout can otherwise result in the same message going out twice.

Log the full error response (not just the HTTP status), correlate it with the message ID, monitor error-rate trends by category, and reproduce the specific failing payload in a test environment rather than guessing from partial logs.

Meta publishes and maintains the official WhatsApp Cloud API error code reference. This page covers the categories and codes developers hit most often; check Meta's current documentation for the complete, up-to-date list, since codes and meanings can change.

No. An API error is returned when your send request itself fails (bad auth, bad payload, etc.). A webhook error is about your endpoint not correctly receiving or processing delivery events - see WhatsApp API Webhooks for that troubleshooting checklist.

It usually means the number isn't reachable on WhatsApp, is formatted incorrectly, or the recipient has opted out of receiving your messages - see the Recipient Errors table for the specific conditions.