Message delivery errors

Where failures surface

When a WhatsApp send fails, the message record carries three fields, readable at GET /v1/messages/{message_id}:

{
  "status":        "failed",
  "error_code":    "provider_error",
  "error_message": "Message undeliverable: Message Undeliverable.",
  "provider_error": {
    "code":       131026,
    "message":    "Message Undeliverable",
    "error_data": { "details": "Message Undeliverable." },
    "fbtrace_id": "A..."
  }
}

error_code is a stable, registered Tyxter code — safe to branch on. error_message is human-readable and may change. provider_error is the raw error object from Meta, preserved verbatim for diagnosis. Failures reach you two ways: rejected inline when you create the message, or reported later by Meta and delivered to your webhook endpoint as a message.failed event. Both paths record the same fields on the message.

The bounded mapping

error_code is never a raw provider string. Known Meta failure codes map to specific Tyxter codes; everything else maps to provider_error with the Meta detail preserved:

Meta code	Tyxter `error_code`	What to do
190	`provider_connection_unauthorized`	The stored WhatsApp connection credential is expired or revoked. Every send on that connection fails until it is reconnected in the dashboard. Retrying cannot succeed.
131047	`service_window_required`	Free-form message outside the 24-hour customer service window (opened by an inbound message from the recipient). Send an approved template instead — `GET /v1/templates`.
132000 / 132001 / 132007	`template_param_mismatch`	The template name, language, or variables don't match the approved template. Compare your send against the approved version before retrying.
anything else	`provider_error`	Meta accepted the request shape but reported a failure. Interpret the numeric code inside `provider_error` — the most common one is documented below.

Meta 131026 — Message Undeliverable

The most common provider_error on production sends is Meta code 131026("Message Undeliverable"): Meta could not deliver to that specific recipient. It is recipient-specific and it is not transient — retrying the identical send will fail again. The strongest diagnostic is comparison: when the same template and sender deliver to other recipients, your template, sender, and Tyxter configuration are all working, and the cause is one of:

The recipient can't receive it— the number is not an active WhatsApp account, runs a very old WhatsApp client, or the user hasn't accepted WhatsApp's current terms of service.
Your WhatsApp Business Account has limited reach — an unverified business is capped to a small set of unique recipients, and Meta refuses delivery beyond it. Check the business verification status and messaging limits in Meta Business Manager / WhatsApp Manager.
Meta declined this sender-to-recipient pair— the user blocked the sender, or Meta's per-user marketing-message limits throttled another marketing template to that user.

To self-diagnose from Tyxter: read the sender's health at GET /v1/phone-numbers/{phone_number_id}— the response carries the Meta quality rating and messaging-tier metadata — and read the failing message's provider_error detail at GET /v1/messages/{message_id}. A 131026failure originates inside Meta's delivery network; the send left Tyxter correctly, so there is no Tyxter-side configuration to fix.

Sandbox

In sandbox, delivery is simulated and no real phone is ever contacted, so Meta deliverability codes such as 131026 occur only on production sends. To rehearse failure handling deterministically, use the sandbox delivery-failure scenarios — see the /sandbox guide.