Meta API Error Reference

Meta Graph and WhatsApp Cloud API errors can appear in two places:

• The immediate API response when your backend calls Meta.
• A later statuses[].errors[] object in a message-status webhook (asynchronous). Some errors arrive through both channels.

Dualhook does not proxy outbound sends or message-status webhooks, so message-send failures happen in your own backend and in the webhook endpoint you configured with Webhook Override. This page is a comprehensive reference for the WhatsApp Cloud API and Graph API error codes — what they mean, where they appear, and how to fix them. Build your handling logic around the numeric code and error_data.details, not titles or HTTP status (Meta is deprecating titles and error_subcode).

Where Errors Appear

Immediate API response

If Meta rejects a request before accepting it, your sender receives an HTTP error and an error object immediately. Examples: invalid token, missing parameter, wrong template variable count, permission issue.

Status webhook after the send

If Meta accepts the request but later cannot deliver the message, your webhook receives a failed status with statuses[].errors[]. Cloud API surfaces asynchronous errors under entry.changes.value.errors and entry.changes.value.messages.errors. Examples: recipient cannot receive the message, pair rate limit, user stopped marketing messages.

Error Object Format

Most API failures return an error object with this shape:

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput has been reached."
    },
    "error_subcode": 2494055,
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

Always log: error.code, error.message, error_data.details, and fbtrace_id. error_subcode is deprecated and is not returned on v16.0+ — do not build logic around it.

Status webhooks use a similar shape inside statuses[].errors[]:

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

Quick Triage

Authorization and Permission Errors

Integrity and Policy Errors

Request and Parameter Errors

Delivery Errors

Throttling and Rate-Limit Errors

Template Creation Errors

Template Send Errors

Marketing Message Errors

The Marketing Messages API for WhatsApp (MM Lite) reuses Cloud API codes with these additions:

Flows Errors

Phone Number and Registration Errors

Payment and Billing Errors

Phone Migration Errors

WABA and OBO Ownership Errors

Coexistence Synchronization Errors

These occur in the Coexistence onboarding flow when syncing contacts/history from the WhatsApp Business app.

Template Insights Errors

Server and Generic Errors

What to Send Support

When asking Dualhook or Meta support about a send failure, include:

• The full error.code, error.message, error_data.details, and fbtrace_id.
• Whether it came from an API response or a status webhook.
• The wamid / message ID if Meta accepted the send.
• The phone number ID and WABA ID.
• The template name + language, if it was a template send.
• The timestamp and Graph API version.

Do not send message content unless support explicitly needs a redacted payload shape. Dualhook support can usually diagnose setup, permissions, template, or health issues from metadata.

Error Handling Strategy

Retryable:

• 4 / 80007 / 130429 / 131056 rate and throughput limits (with backoff)
• 1 / 2 / 131000 / 131016 / 133004 transient server failures
• Network timeout/connectivity errors

Usually non-retryable without payload, access, or account changes:

• 100 / 131008 / 131009 / 131051 validation errors
• 0 / 10 / 190 / 200 / 131005 auth and permission errors
• 132000 / 132001 / 132012 template errors
• 131047 service-window violations (send a template instead)
• 131049 / 131050 / 131063 marketing preference or policy failures
• 368 / 130497 / 131031 integrity/policy restrictions
• 137000 identity-key mismatches (re-verify the recipient)

Suggested Retry Policy

1. Use exponential backoff with jitter.
2. Cap retry attempts for transient classes (3–6 attempts).
3. Send non-retryable errors directly to a dead-letter/ops queue.
4. Include idempotency keys in sender jobs to avoid duplicate sends.
5. Always store fbtrace_id for support escalation.

Dualhook surfaces webhook-side delivery errors and management alerts in monitoring views. Message-send API failures happen in your backend caller and should be logged there with full Graph error metadata.