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.
How to read a send failure
Section titled “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:code,meta_code(Meta’s original code, when the error came from Meta),details,retryable,retry_after_mson limit errors,request_idanddocs_url. Handle the error bycode, never by themessagetext. On a Meta error,details[0].messagecarries the detail Meta sent. - Later, through the webhook. Meta can accept the send and fail it afterwards. In that case you receive the
message.statusevent with statusfailed. See Events.
Retry only when retryable is true. The table at the end of the page sums up every code.
Payment
Section titled “Payment”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.
The template does not go out
Section titled “The template does not go out”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.
The marketing template does not arrive
Section titled “The marketing template does not arrive”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.
Outside the window
Section titled “Outside the window”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.
Recipient
Section titled “Recipient”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.
Throughput
Section titled “Throughput”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.
Connection
Section titled “Connection”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.
Unknown outcome
Section titled “Unknown outcome”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).
Retry or not
Section titled “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
Section titled “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.