# Message delivery errors

Canonical: https://tyxter.com/docs/delivery-errors
Section: Messaging

How provider failures surface on a message, the stable error codes they map to, and how to troubleshoot WhatsApp deliverability (Meta 131026 and friends).

# Message delivery errors

When a WhatsApp send fails, the message record carries three fields you can read at GET /v1/messages/{message_id}: `error_code` — a stable, registered Tyxter code that is safe to branch on; `error_message` — a human-readable reason; and `provider_error` — the raw error object from Meta (numeric `code`, `error_subcode`, title and details text, and Meta's `fbtrace_id`), 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.

`error_code` is bounded — it is never a raw provider string. Known Meta failure codes map to specific Tyxter codes, and everything else maps to `provider_error` with the Meta detail preserved:

- Meta `190` maps to `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 without reconnecting cannot succeed.
- Meta `131047` maps to `service_window_required`: a free-form message was sent outside the 24-hour customer service window (opened by an inbound message from the recipient). Send an approved template instead — list them at GET /v1/templates.
- Meta `132000`, `132001`, and `132007` map to `template_param_mismatch`: the template name, language, or variables do not match the approved template. Compare your send against the approved version before retrying.
- Anything else maps to `provider_error`: Meta accepted the request shape but reported a failure. Interpret the numeric code inside the message's `provider_error` field — 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 cannot receive the message: the number is not an active WhatsApp account, runs a very old WhatsApp client, or the user has not 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 `131026` failure originates inside Meta's delivery network; the send left Tyxter correctly, so there is no Tyxter-side configuration to fix.

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).