message.failed▾
message.failed
Delivery failed permanently. The error explains why.
Terminal — the message will not be retried. Read error.code before deciding whether to resend; most failures are not retryable.
EVENT
message.failedPayload
{
"id": "evt_01JZQ6F5H7K9M1P3R5T7V9XZBD",
"object": "event",
"type": "message.failed",
"created_at": "2026-09-06T09:41:02.114Z",
"api_version": "2026-09-01",
"data": {
"object": "message",
"id": "msg_01JZQ3F8X2K7N4B6Y0R9M5TCWA",
"to": "+201005550123",
"status": "failed",
"error": {
"code": "recipient_not_on_whatsapp",
"title": "Recipient is not a WhatsApp user",
"message": "+201005550123 has no WhatsApp account on this number.",
"meta_code": 131026
},
"status_at": "2026-09-06T09:41:05.000Z"
}
}Notable fields
error.codestringrequiredSendport error code — see the table below.
error.meta_codeintegerMeta's own numeric code, useful when escalating to WhatsApp support.
| Code | Retry? | What to do |
|---|---|---|
recipient_not_on_whatsapp | No | Mark the contact unreachable |
contact_opted_out | No | Stop messaging — they blocked you or replied STOP |
session_window_closed | No | Resend as a template |
template_paused | No | Meta paused the template for low quality; fix and resubmit |
messaging_limit_reached | Later | You hit the daily unique-contact tier; retry tomorrow |
reengagement_required | No | Send an approved template first |