Troubleshoot WhatsApp Delivery Failures by Error Code

This guide shows you how to diagnose WhatsApp messages that fail after the API accepted them, and how to resolve each of the per-message error codes that WhatsApp sends produce. It assumes your WhatsApp channel is already connected and sending; for connection and onboarding problems, see WhatsApp Onboarding & Business Account Connection.

Rule Out a Synchronous API Error First

A rejected API call and a failed delivery are different problems:

• Synchronous API errors come back in the HTTP response. The call returns 4xx with an envelope code such as AUTH_002 or VALIDATION_002. Fix the request itself; refer to the error handling reference for the envelope format and the full code list.
• Asynchronous delivery failures happen after POST /v3/messages responds 202 Accepted. Each message is processed and finalized on its own, so a message can fail minutes after a successful API call. These failures carry the ERR_* codes covered in this guide, which never appear in the HTTP response.

If your API call returned 2xx but the message shows as failed, you are debugging an asynchronous delivery failure. Continue below.

Locate the Failure

A failed delivery surfaces in four places:

• GET /v3/messages/{id}: the status field reads FAILED, and channel shows the channel of the most recent attempt.
• GET /v3/messages/{id}/activities: the lifecycle log ends in a FAILED activity.
• The message.failed webhook event pushes the failure to your endpoint as it happens.
• Dashboard → Activities shows the same timeline for each message.

curl https://api.sent.dm/v3/messages/8ba7b830-9dad-11d1-80b4-00c04fd430c8/activities \
  -H "x-api-key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "activities": [
      {
        "status": "FAILED",
        "description": "Message updated to FAILED",
        "from": "+15551234567",
        "timestamp": "2026-07-24T15:00:20Z",
        "price": null,
        "active_contact_price": null
      }
    ]
  }
}

Match the Code to a Fix

ERR_MESSAGE_UNDELIVERABLE

Meta accepted the message (the send call succeeded and returned a WhatsApp message ID), then reported it undeliverable in a later delivery status callback. Sent maps Meta's undeliverable failure, WhatsApp error 131026, to this code. It is a recipient-side failure: the recipient cannot currently receive WhatsApp messages from your number.

Sent handles it automatically:

1. The WhatsApp attempt is recorded as FAILED and a message.failed webhook fires with "channel": "whatsapp".
2. WhatsApp is paused for that recipient for 30 days: routing skips WhatsApp for them until the pause expires.
3. The same message is re-sent through SMS routing. Fresh lifecycle events arrive for the same message_id with "channel": "sms", and the message's channel field changes to sms.

You do not need to fix anything per message: watch for the SMS attempt's outcome (message.delivered with "channel": "sms"). If sends to a recipient repeatedly end here, treat that number as unreachable on WhatsApp and message them over SMS. The 30-day WhatsApp pause expires on its own.

ERR_TEMPLATE_PARAMS_INVALID

The variables submitted with the send do not satisfy the template. Both Sent and Meta raise this code:

• Sent's send pipeline blocks the message when a required template variable is missing, a value contains new-line or tab characters or more than 4 consecutive spaces (Meta's parameter text rules), or a value fails the variable's validation pattern.
• Meta rejects the dispatch with error 100 (invalid parameter) when the payload does not match the approved template, for example the wrong variable count, or a plain string where the template expects a currency or date-time object.

The message stays FAILED; there is no SMS fallback and no automatic retry. To resolve:

1. Open the template in Dashboard → Templates and compare its placeholders against the variables in your request: supply every placeholder, and remove extras.
2. Strip new-lines, tabs, and long runs of spaces from variable values.
3. Send a corrected message.

If the template itself is the problem (rejected, miscategorized, or stuck in review), see WhatsApp Template Issues.

ERR_TEMPLATE_NAME_INVALID

Meta rejected the send because no template with that name exists on the WhatsApp Business Account for the language sent. Meta's error message reads template name does not exist in the translation.

To resolve:

1. Confirm the template exists and shows Approved in Dashboard → Templates.
2. If you manage templates directly in Meta's WhatsApp Manager, confirm the template was not renamed or deleted there, and that it exists in the language you are sending.
3. Send a corrected message. The failed message stays FAILED; there is no SMS fallback and no automatic retry.

ERR_RECIPIENT_NOT_REGISTERED

The recipient's phone number is not registered on WhatsApp. Sent maps Meta error 133016, and provider messages stating the number is not a WhatsApp user, to this code.

For a genuine unregistered recipient, Sent reacts the same way as for ERR_MESSAGE_UNDELIVERABLE: WhatsApp is paused for that recipient for 30 days and the message is re-sent through SMS routing under the same message_id. No action is needed beyond confirming the SMS attempt delivered.

ERR_PROVIDER_ERROR

The catch-all code: the provider returned an error that Sent could not map to any specific code. It appears on WhatsApp and on SMS carriers alike. Unclassified failures deliberately do not trigger an automatic re-send, so the message stays FAILED.

To resolve:

1. Check the Sent status page for an ongoing incident.
2. Contact support with the message ID to get the raw provider response.
3. If the cause was transient, send the message again.

ERR_ECOSYSTEM_ENGAGEMENT

Meta's anti-spam restriction, WhatsApp error 131049: Meta declined to deliver the message because its systems flagged the send as spam-like. Sent treats it as a recipient-side failure, so the message is automatically re-sent through SMS routing and WhatsApp is paused for that recipient for 30 days.

For the causes and prevention steps (the 24-hour conversation window, template reclassification, send frequency), see ERR_ECOSYSTEM_ENGAGEMENT in Messages Not Delivered.

When Failures Fall Back to SMS

Two separate mechanisms can move a WhatsApp send to SMS:

• After Meta accepts, on a recipient-side failure. ERR_MESSAGE_UNDELIVERABLE, ERR_RECIPIENT_NOT_REGISTERED, and ERR_ECOSYSTEM_ENGAGEMENT trigger an automatic re-send of the same message over SMS, plus the 30-day per-recipient WhatsApp pause. You observe a message.failed event with "channel": "whatsapp" followed by new lifecycle events for the same message_id with "channel": "sms".
• At send time, before Meta accepts. If the WhatsApp send call itself fails and your routing allows fallback, Sent immediately tries the next eligible route in the same send. See WhatsApp-to-SMS failover for debugging that path.

Template and unclassified errors (ERR_TEMPLATE_PARAMS_INVALID, ERR_TEMPLATE_NAME_INVALID, ERR_PROVIDER_ERROR) never fall back: the message stays FAILED, and you must fix the cause and send a new message.

Verify the Resolution

After applying a fix, send the message again and confirm delivery:

• GET /v3/messages/{id} returns "status": "DELIVERED", or a message.delivered webhook arrives.
• For the automatic-fallback codes, confirm the SMS attempt delivered: the terminal event carries "channel": "sms".

Related

• Messages Not Delivered: API-vs-dashboard mismatches, country-specific SMS filtering, and sender routing issues
• WhatsApp Template Issues: template approval, categorization, and rejection problems
• Error Handling: the API error envelope, HTTP status codes, and the full send-time ERR_* code table
• Message Status Tracking: tracking delivery status by webhook, polling, and dashboard