# Send failures: payment and templates

> Why a send fails because of the payment method or a template, and how to fix it.

Each symptom below follows the same shape: what you see, the cause and what to do. The meaning and action texts are the same as in the [error catalog](/en/errors/).

## How to read a send failure

A failure reaches you in one of two ways:

- **In the response of `POST /v1/messages`.** The error comes in the [standard format](/en/errors/#error-format): `code`, `meta_code` (Meta's original code, when the error came from Meta), `details`, `retryable`, `retry_after_ms` on limit errors, `request_id` and `docs_url`. Handle the error by `code`, never by the `message` text. On a Meta error, `details[0].message` carries the detail Meta sent.
- **Later, through the webhook.** Meta can accept the send and fail it afterwards. In that case you receive the `message.status` event with status `failed`. See [Events](/en/webhooks/events/).

Retry only when `retryable` is `true`. The table at the end of the page sums up every code.

## Payment

**You see:** `402` [`meta_payment_required`](/en/errors#meta_payment_required), with `meta_code` 131042.

**Cause:** the WhatsApp Business account has no valid payment method, the payment failed or the credit limit ran out. Message billing belongs to Meta, not to Messajo.

**What to do:** fix the payment method in Meta Business Manager. In the panel, the connection's **Health** card shows the same problem with code 141006 and the action **Add a payment method**. Meanwhile, replies to customers who wrote in the last 24 h keep working; templates, which start conversations, do not.

## The template does not go out

**You see:** `422` [`template_error`](/en/errors#template_error), with `meta_code` 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068 or 132069.

**Cause:** the template does not exist in that language, the parameters do not match in count or format, the text went over the limit, or the template is paused or disabled.

**What to do:** read `details[].message` and `meta_code`. Check name, language and parameters under **Templates**; a paused or disabled template has to be edited. See [Templates](/en/guides/templates/).

**You see:** `404` [`template_not_found`](/en/errors#template_not_found).

**Cause:** there is no template with that id, or with that name and language, in this WhatsApp Business account.

**What to do:** check the name and language, or sync the list with `POST /v1/templates/sync`.

**You see:** `422` [`otp_template_invalid`](/en/errors#otp_template_invalid).

**Cause:** the authentication template you named does not exist or is not `APPROVED`.

**What to do:** create the template with `POST /v1/templates/authentication` and wait for approval before sending codes. See [Authentication templates](/en/guides/authentication-templates/).

**You see:** the template stays `PENDING` or shows up as `REJECTED`.

**Cause:** only an approved template can be sent. The status comes from Meta and arrives in the `template.status` event.

**What to do:** wait for approval, or edit the rejected template and submit it again. See the [lifecycle](/en/guides/templates/#lifecycle).

**In campaigns,** two extra codes can appear. [`campaign_template_not_approved`](/en/errors#campaign_template_not_approved): the template is not `APPROVED` or belongs to a category that cannot be used in a campaign (only `MARKETING` and `UTILITY`). [`campaign_template_mapping_invalid`](/en/errors#campaign_template_mapping_invalid): a parameter has no source in `variable_mapping`; `details` shows the `path` of each one. See [Campaigns](/en/guides/campaigns/).

## The marketing template does not arrive

**You see:** `422` [`marketing_limit_reached`](/en/errors#marketing_limit_reached), with `meta_code` 131049.

**Cause:** Meta held the marketing template to keep the contact's engagement healthy (a per-user limit).

**What to do:** do not resend right away. Wait a few days or send something the contact asks for; an immediate resend does not go through.

**You see:** `429` [`meta_spam_rate_limited`](/en/errors#meta_spam_rate_limited), with `meta_code` 131048.

**Cause:** too many messages from this number were reported or blocked. Campaigns pause on their own with this error.

**What to do:** do not resend. Review the list (only people who asked to receive), the template content and the frequency, and wait for the number's quality to recover before resuming.

## Outside the window

**You see:** `422` [`outside_service_window`](/en/errors#outside_service_window), with `meta_code` 131047.

**Cause:** the contact has not written for more than 24 h (72 h if they came from an ad), and only a template can open the conversation. The end of the window comes in `details[0].message`.

**What to do:** send an approved template. When the contact replies, the window opens again. See [Windows](/en/api/limits/#windows).

## Recipient

**You see:** `422` [`recipient_unavailable`](/en/errors#recipient_unavailable), with `meta_code` 131026.

**Cause:** the number has no WhatsApp, the contact's app is out of date or they have not accepted the new terms.

**What to do:** check the number with its country code. Do not retry right away: the result is the same until the recipient fixes it on their side.

**You see:** `422` [`recipient_not_allowed`](/en/errors#recipient_not_allowed), with `meta_code` 131030.

**Cause:** Meta's test number only sends to the recipients registered in its app.

**What to do:** register the recipient in the Meta app dashboard or connect a real number.

## Throughput

**You see:** `429` [`connection_rate_limited`](/en/errors#connection_rate_limited).

**Cause:** the number is already sending at the top speed of its tier (20 msg/s in coexistence, 80 or 1000 msg/s on API only). `typing` also spends a slot.

**What to do:** wait `retry_after_ms` and retry. Nothing is queued: your integration does the retry. See [Limits](/en/api/limits/#sending-per-number).

**You see:** `429` [`pair_rate_limited`](/en/errors#pair_rate_limited), with `meta_code` 131056.

**Cause:** the pair limit (this number and this contact) was reached. Other contacts are not affected.

**What to do:** wait `retry_after_ms` (6 s) before sending to the same contact again.

**You see:** `429` [`meta_rate_limited`](/en/errors#meta_rate_limited), with `meta_code` 130429, 80007 or 4.

**Cause:** Meta refused because of a throughput limit on the number, the account or the app, without processing the request.

**What to do:** wait `retry_after_ms` (or the `Retry-After` header) and retry.

## Connection

**You see:** `409` with one of these codes.

| Code | Cause | What to do |
|---|---|---|
| [`connection_needs_reconnect`](/en/errors#connection_needs_reconnect) (`meta_code` 190 or 102) | The Meta token was revoked or expired. | Reconnect from the panel or from the link in the email we sent. Nothing goes out until you reconnect. |
| [`connection_restricted`](/en/errors#connection_restricted) | Meta restricted the connection. | See [Number restricted or banned](/en/troubleshooting/number-restricted/). |
| [`connection_disabled`](/en/errors#connection_disabled) | Meta disabled the connection. | See [Number restricted or banned](/en/troubleshooting/number-restricted/). |
| [`connection_disconnected`](/en/errors#connection_disconnected) | The connection was disconnected. | Connect again from the panel. |
| [`connection_pending`](/en/errors#connection_pending) | The connection signup is not finished. | Finish the connection in the panel. |
| [`number_not_registered`](/en/errors#number_not_registered) (`meta_code` 133010) | The number's Cloud API registration failed or was undone. | Open the connection and use **Retry registration**. If it persists, reconnect the number. |

## Media

**You see:** `422` [`media_error`](/en/errors#media_error) (`meta_code` 131052, 131053 or 131051), `413` [`media_too_large`](/en/errors#media_too_large) or `415` [`media_type_not_supported`](/en/errors#media_type_not_supported).

**Cause:** Meta did not download or did not accept the media: unsupported type, file too large or unreachable link.

**What to do:** read `details[].message`. Check the accepted type and size (image 5 MiB, audio and video 16 MiB, document 100 MiB) and, if you sent a link, that it is public and answers quickly. Convert to an accepted format (JPEG or PNG, MP4, OGG with Opus, PDF) or send it as a document. See [Send image](/en/send/image/).

## Unknown outcome

**You see:** `502` [`meta_unknown_outcome`](/en/errors#meta_unknown_outcome).

**Cause:** a timeout or a temporary Meta failure during a send. There is no way to know whether the message went out; it stays `queued` until the status arrives by webhook.

**What to do:** do not resend blindly. Confirm via `message.status` or with the contact. Repeating with the same `Idempotency-Key` returns the same 502 without resending; to send again on purpose, use a new key. The SDK never retries this error (see [Safe retries](/en/sdk/typescript/#safe-retries)).

## Retry or not

| Code | Status | Retry? |
|---|---|---|
| `meta_payment_required` | 402 | No: fix the payment |
| `template_error` | 422 | No: fix the template |
| `template_not_found` | 404 | No: fix the name or sync |
| `otp_template_invalid` | 422 | No |
| `campaign_template_not_approved` | 422 | No |
| `campaign_template_mapping_invalid` | 422 | No |
| `marketing_limit_reached` | 422 | No |
| `meta_spam_rate_limited` | 429 | No |
| `outside_service_window` | 422 | No: send a template |
| `recipient_unavailable` | 422 | No |
| `recipient_not_allowed` | 422 | No |
| `connection_rate_limited` | 429 | Yes, after `retry_after_ms` |
| `pair_rate_limited` | 429 | Yes, after `retry_after_ms` |
| `meta_rate_limited` | 429 | Yes, after `retry_after_ms` |
| `connection_needs_reconnect` | 409 | No: reconnect |
| `connection_restricted`, `connection_disabled`, `connection_disconnected`, `connection_pending` | 409 | No |
| `number_not_registered` | 409 | No |
| `media_error` | 422 | No |
| `media_too_large` | 413 | No |
| `media_type_not_supported` | 415 | No |
| `meta_unknown_outcome` | 502 | Not blindly: confirm via `message.status`; the same `Idempotency-Key` returns the same 502, use a new key to resend |

## Contact support

Send the error's `request_id`, which is the same value as the `X-Request-Id` header. With it, support finds the exact call without you having to send your key. See [X-Request-Id for support](/en/api/authentication/#x-request-id-for-support).
