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":    "meta_message_undeliverable",
  "error_message": "Message undeliverable: Message Undeliverable. Retry addressing the recipient by phone number instead of a business-scoped user id, and remove links from the message if you are sending to one.",
  "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; for a mapped code it ends with the next step to take. 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, and the message.failed payload carries error_code, error_message and provider_error inline — so a webhook receiver does not have to call back to learn why the send failed.

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:

WABA send-capability blocks

A fresh stored WABA block terminates a queued send before Meta is called, with a stable receipt and provider_error: null. When a Meta send error instead causes Tyxter to confirm that the connected WABA is blocked, that reactive receipt is also terminal and is not retried unchanged. Meta health code 141006 records meta_payment_method_required: add a payment method in WhatsApp Manager → Billing & payments. 141008 records meta_waba_inactive: reactivate the WABA in WhatsApp Manager or ask Meta support. 141011 records meta_messaging_permission_missing: reconnect and grant the requested WhatsApp messaging permissions, then ask support if it persists. If Meta reports more than one of these diagnostics, the primary remediation is deterministic: payment, inactive WABA, then messaging permission.

A reactive receipt retains the original bounded send failure in provider_error, even when its provider code was generic; the pre-send stored-block receipt has provider_error: null. The capability observation supplies the stable error_codein both cases. This does not suspend the connection or phone number, and inbound messages remain available. After the account is fixed, a positive Meta health observation clears that WABA's capability evidence so a later send can continue. Read the connection's optional waba_send_capabilities entry matching the sender waba_id for the latest trusted diagnosis. The singular send_capability, send_block_codes, and send_capability_observed_atfields are the compatibility view for the connection's primary WABA.

Failures that never reach Meta

Seven codes are stamped before any provider call, so a message carrying one has no provider_error to read — nothing was sent and nothing was billed. They are as stable and as safe to branch on as the mapped codes above.

• no_provider_connection — the environment has no WhatsApp connection at all, so there is nothing to send through. Connect WhatsApp from the dashboard, then resend. Keep it apart from the three codes that mean a connection does exist: provider_connection_unauthorized (the stored credential died — re-authenticate), provider_connection_suspended (Meta acted against the account — appeal), and meta_registration_required (setup began and stopped before Meta finished registering the number — finish it from the dashboard link in the message text). Retrying without connecting cannot succeed.
• sender_phone_number_unavailable— an accepted message named a sending phone Tyxter cannot use. It deliberately gives no more specific reason, does not fall back to the connection's primary number, and never reaches Meta. Choose an active WhatsApp phone linked to Meta, then resend. Older messages with no sender continue using their connection default for compatibility.
• invalid_template_payload — a template message reached the sender without both template.name and template.language, so there was no template to resolve. Resend with both fields set; it is not retryable unchanged.
• phone_number_rate_limit_exhausted— the send was rescheduled repeatedly because the sending phone number was over its throughput budget, and it was still over after the last reschedule. Nothing about the message is wrong; it lost a queue for capacity. Spread the traffic over a longer window, send from more numbers, or raise the phone number's throughput before resending.
• media_asset_resolution_failed — Tyxter could not resolve the media attached to the send and the failure carried no more specific cause. The expected media problems have their own codes and never land here: media_asset_not_found, media_asset_expired and media_asset_not_ready for the asset itself, and media_link_fetch_failed, invalid_media_mime_type and media_too_large for a media.link. This is the residual bucket, so a repeat is worth reporting with the message's trace_id rather than retried indefinitely.
• media_voice_requires_ogg_opus — a requested voice note resolved to known audio whose normalized MIME is not audio/ogg, so delivery stops before a provider call. Meta requires OGG/Opus mono audio, but Tyxter checks only the MIME it knows; it does not inspect codecs or channels, or convert media. Use ordinary audio (omit voice) or provide OGG/Opus mono audio.
• provider_send_result_missing — stale-send recovery found a message left in sendingwithout a provider message id and without evidence that a provider call started. The message is failed rather than sent again, avoiding an untracked duplicate. Report repeated occurrences with the message's trace_id.

TTS render failures

TTS audio is rendered before WhatsApp is called. tts_provider_errormeans the configured speech provider rejected or could not complete the render after retries; the message's provider_error carries a bounded provider name and, when available, status_code. tts_render_failed means rendering failed outside a provider response, such as storage or unexpected processing failure. In both cases the message never reached WhatsApp. Use the message trace_id when reporting a repeated tts_render_failed.

Media links Tyxter retrieves

When a media message carries message.media.link, Tyxter retrieves that file and uploads it to WhatsApp, then sends by the uploaded media id instead of passing your URL along. Nothing about the request changes: you still send media.link, GET /v1/messages/{message_id}still shows the message you created, and no new field appears. What changes is which failures you can see. Meta's own weblink fetch was the single largest source of 131053, and it gave you nothing to act on beyond the word "failed"; a retrieval Tyxter performs can say exactly what went wrong, and it lets the accepted-type and size rules that already apply to uploads apply to links too. A broadcast also retrieves and uploads the file once per sending phone number rather than once per recipient, so your origin is not hit thousands of times.

media_link_fetch_failed is the stable code for that retrieval failing: Tyxter could not get the bytes. The host did not resolve, refused the connection, or was rejected as a private or internal address; the request timed out; the URL answered a non-2xx status; it redirected more than three times; or it returned an empty body. Transient causes (DNS blips, timeouts, connection resets, 429 and 5xx answers) are retried automatically and stamp the code only once the attempts are exhausted; the rest fail the message on the first attempt, because retrying an unreachable or forbidden URL only repeats the same answer. To fix it, make the URL publicly reachable without authentication — https is strongly recommended and plain http is also accepted — serve the file bytes directly rather than an HTML preview or a login page, and answer within 30 seconds. The most reliable fix is to skip URLs entirely — upload the file once at POST /v1/media/uploads and send it by asset_id.

Two other codes surface on the same retrieval, and both mean Tyxter got the bytes and refused them. invalid_media_mime_type means the URL answered without a Content-Type header at all, or with one WhatsApp does not accept for that media kind — the same accepted set POST /v1/media/uploads enforces, so a URL cannot deliver a type an upload of the same file would have been refused. media_too_large means the response exceeded the per-kind size limit; the download is cancelled mid-stream rather than read to the end.

Keep media_link_fetch_failed and meta_media_download_failed apart, because the remediation differs: the first means Tyxter could not retrieve your URL and the message never reached Meta; the second means Meta could not fetch or use media handed to it. For the same reason, media_link_fetch_failed never means a provider rejected your send — no provider was contacted.

Retrieval covers the mediamessage type only, so several sends still pass a raw link through unchanged and Meta's 131053 remains the code to read for them. An interactive message header that carries a link is still delivered as a link: that header accepts only id — a media id you already hold at Meta — or link, and Tyxter does not issue Meta media ids, so there is no upload path for it through this API today. Flow message headers are text-only and never carry media at all. Template header media is always referenced by asset_id and is uploaded before the send, but a header image supplied as a raw link inside template.components bypasses this entirely and is passed through untouched. Also unretrieved: a link whose scheme is not http or https, channels whose provider has no media upload API (Instagram), and rare operational fallback modes. In sandbox, delivery is simulated and no URL is ever retrieved.

When Meta has acted against your WhatsApp account

provider_connection_suspended is the stable code for a send that never left Tyxter because Meta acted against the WhatsApp Business Account behind the connection — it was banned, rejected at account review, restricted, legacy-suspended with scheduled_for_disable, or the grant was lost because Tyxter's app was removed or the account was deleted. It is not a deliverability problem with the recipient and it is not a Meta-mapped code: the connection is suspended, so every send on it fails before any provider call and there is no provider_errorto read. This is deliberately wider than Meta's own action — a restriction or a legacy scheduled-disable suspension still leaves some sending possible at Meta, and Tyxter stops anyway rather than pushing traffic through an account Meta has already flagged.

Keep current SCHEDULE_FOR_DISABLE evidence separate: on a connected connection, nullable waba_ban_date is advisory and sends continue until Meta actually disables the account. Only an actual suspended connection receives this error.

Retrying cannot succeed until the account state changes, so treat it as an operator alert rather than a retryable failure. Read suspension_reason on the connection (GET /v1/provider-connections/{connection_id}) for the machine-readable reason, or the whatsapp channel's reason on GET /v1/provider-connections/status, which reports policy_suspended for this case. The remedy follows the reason: appeal the account at business.facebook.com/accountquality when it was banned, rejected at review, restricted, or legacy-suspended for disablement — replacing or re-authorizing the access token cannot lift any of those, because the credential is not what Meta acted on — and reconnect WhatsApp from the dashboard when the reason is app_uninstalled or account_deleted, where connecting again really is the fix.

Keep it apart from provider_connection_unauthorized, which means the stored credential expired or was revoked and re-authenticating restores sends. Its write-path twin is provider_connection_policy_suspended, the 409 a credential write (rotate, register, complete registration) gets for the same account state; see the /errors page. Sends resume on their own once Meta clears the account and the connection returns to connected.

Meta 131026 — Message Undeliverable

The most common delivery failure on production sends is Meta code 131026 ("Message Undeliverable"), which maps to meta_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 contacted outside their customer-service windows. This is not a cap on the number of messages. 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.
• You addressed a business-scoped user id and the message contains a link — the same 131026 is returned. Retry addressing the recipient by phone number, or send the message without the link.

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 scenarios. They stamp the registered codes sandbox_delivery_failure, sandbox_recipient_opted_out, and sandbox_template_rejected. These are simulated terminal outcomes, carry no provider_error, and appear on the same message read and message.failed webhook surfaces as production delivery codes. See the /sandbox guide.