Skip to content

Troubleshooting

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.

A failure reaches you in one of two ways:

  • In the response of POST /v1/messages. The error comes in the standard 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.

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

You see: 402 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.

You see: 422 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.

You see: 404 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.

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.

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.

In campaigns, two extra codes can appear. 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: a parameter has no source in variable_mapping; details shows the path of each one. See Campaigns.

You see: 422 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, 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.

You see: 422 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.

You see: 422 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, 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.

You see: 429 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.

You see: 429 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, 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.

You see: 409 with one of these codes.

Code Cause What to do
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 Meta restricted the connection. See Number restricted or banned.
connection_disabled Meta disabled the connection. See Number restricted or banned.
connection_disconnected The connection was disconnected. Connect again from the panel.
connection_pending The connection signup is not finished. Finish the connection in the panel.
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.

You see: 422 media_error (meta_code 131052, 131053 or 131051), 413 media_too_large or 415 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.

You see: 502 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).

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

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.