Skip to content

Webhook Error Objects

The errors arrays WhatsApp webhooks carry on failed statuses, unsupported inbound messages and system-level problems, each with a code, title and details.

Also called: Webhook error object · errors array · Failed status webhook · statuses[].errors · value.errors · Webhook error payload

Reviewed

Interactive lab

Hands on: use the controls to explore. Anything that plays on its own pauses while you are working inside it.

Take apart a failed-status webhook

5 / 5
{
"object": "whatsapp_business_account",
"entry": [{
"id": "102290129340398",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "919876543210", "phone_number_id": "106540352242922" },
"statuses": [{
"id": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSQjc4RTFDMEFG",
"status": "failed",
"timestamp": "1792392000",
"recipient_id": "919812345678",
"errors": [{
"code": 131026,
"title": "Message undeliverable",
"message": "Message undeliverable",
"error_data": { "details": "Message Undeliverable." },
"href": "https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes"
}]
}]
}
}]
}]
}

Step 5 of 5 · line 20

href points to Meta's error-code reference with causes and fixes.

Jump to
Step through a failed status and its errors array, then a small router that collects errors from all three places and turns each code into an action.

Failed status, step 5 of 5, line 20: href points to Meta's error-code reference with causes and fixes.

01What is a webhook error object?

Webhook error objects are how WhatsApp reports failures that happen after a send is accepted, because many failures cannot be known when you send. The Cloud API accepts a request, returns a wamid, and reports what happened afterwards through webhooks. When something goes wrong, the webhook carries an errors array. Each item has an integer code, a title, a message (Meta documents it as the same text as title), an error_data.details string with the explanation, and usually an href linking to Meta's error-code reference.

The array appears in three places, all under the messages webhook field. On the statuses webhook: value.statuses[].errors accompanies status: "failed", for example 131026 when a recipient cannot be reached or 131050 when the user has stopped your marketing messages. On an inbound message: value.messages[].errors comes with type: "unsupported" — an unsupported message type such as a poll update or an edit — for example 131051 "Message type unknown" for content the Cloud API cannot represent. And at value level: value.errors reports system, app or account problems that are not tied to one status, such as 130429 "Rate limit hit".

These differ from synchronous API errors. When a send request is rejected outright, the HTTP response contains an error object with message, type, code, error_data and the FB trace ID (fbtrace_id), and nothing is sent. Webhook errors arrive later, asynchronously, for requests that were accepted; you tie them back to your send through the wamid. Meta's list of API error codes says errors can come back synchronously, through webhooks or both, and recommends monitoring both channels.

Key takeaways

  • Webhook error objects are the errors arrays WhatsApp sends when something fails after the API has accepted your request.
  • They appear in three places: statuses[].errors on failed statuses, messages[].errors on unsupported messages, and value.errors.
  • Each has an integer code, a title, a message equal to the title, error_data.details and an href to Meta's error reference.
  • Branch on the code: retry 130429 later, wait 24 hours on 131049, suppress on 131050, try another channel on 131026.
  • A message that ends in a failed status is not billed, because Meta charges for delivered messages only.

02A webhook error object in code

"value": {
  "messaging_product": "whatsapp",
  "metadata": {
    "display_phone_number": "919876543210",
    "phone_number_id": "106540352242922"
  },
  "errors": [{
    "code": 130429,
    "title": "Rate limit hit",
    "message": "Rate limit hit",
    "error_data": {
      "details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"
    },
    "href": "https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes"
  }]
}

Not tied to one status: a system, app or account problem reported at value level.

03 · How it works, step by step

How does a webhook error object work?

  1. Step 1

    Subscribe to messages

    All three kinds of webhook error arrive on the messages field. If you already receive inbound messages and statuses, you receive errors too.

  2. Step 2

    Look in all three places

    For each change, collect statuses[].errors on failed statuses, messages[].errors on unsupported inbound messages, and value.errors at the top of the value.

  3. Step 3

    Store the error against the wamid

    Save code, title and error_data.details with the message record, its message status and timestamp, so support can answer "why didn't this arrive?" in one lookup.

  4. Step 4

    Classify by code

    Decide per code: retry later (130429, 131000), wait at least 24 hours (131049), stop and suppress (131050), check the recipient or fall back to another channel (131026), or reply that the content type is unsupported (131051).

  5. Step 5

    Surface it to people

    Show the readable title in the inbox and campaign reports, and alert on a sudden rise of any one code — it usually means a template, a payment method or a throughput limit needs attention.

04 · Common mistakes, and the fix

Common mistakes with a webhook error object

  • Watching only synchronous errors

    A 200 response with a wamid means accepted, not delivered. Track failed statuses too, or failures after acceptance never reach your reports.

  • Retrying every failure

    Retrying 131050 or 131026 straight away only repeats the failure — for 131050 Meta says outright not to retry. Retry only codes where Meta suggests it, and on the schedule it suggests.

  • Parsing the wording instead of the code

    Titles and details can change. Branch on the integer code and treat the text as something to display.

  • Missing value-level errors

    A loop that only walks messages and statuses never sees value.errors. Check for it explicitly on every change in the webhook payload.

05Example: A Lucknow coaching institute's fee reminders

A Lucknow coaching institute sends 18,000 fee-reminder templates. The API accepts every request, but about 6% come back as failed statuses over the next hour. Grouping by errors[].code shows three causes: 131026 for numbers that are not on WhatsApp or run an outdated app, routed to SMS; 131050 for parents who had stopped the institute's marketing — revealing that a promotional line had crept into the template, which the team removes; and a handful of 131049, queued for another attempt after 24 hours (figures illustrative).

06A webhook error object: key facts and limits

Error fields
code · title · message · error_data.details · href
On failed statuses
value.statuses[].errors
On inbound messages
value.messages[].errors (type unsupported)
System-level
value.errors
Webhook field
messages
131049 retry guidance
Wait at least 24 hours
Failed messages billed?
No — Meta bills delivered messages

07Why does a webhook error object matter?

An accepted send is not a delivered message. Without reading webhook errors, dashboards show messages stuck at "sent" forever, campaigns keep re-targeting people who opted out of marketing, OTP flows wait for codes that will never arrive, and support agents cannot tell a customer why their order update never came. Reading the errors array, and acting on its code, turns silent failures into retries, fallbacks and suppressions — and keeps delivery reports honest.

08Webhook Error Objects FAQs

Why did the API accept my message but a failed status arrive later?+
Because acceptance only means the request was valid. Delivery can still fail — the recipient is unreachable, has stopped your marketing, or Meta limited delivery — and that outcome is reported asynchronously in a failed status.
Which webhook field carries WhatsApp errors?+
The messages field carries all three kinds. Failed statuses, unsupported inbound messages and value-level system errors all arrive on the subscription you already use for inbound messages, so no extra field is needed.
Do webhook errors include an fbtrace_id?+
Not as a documented field. Meta's documented webhook error fields are code, title, message, error_data and href; the trace ID belongs to synchronous API responses. For webhook failures, quote the wamid and timestamp when you contact support.
Am I charged for messages that fail?+
No. Meta bills delivered messages, so a message that ends in a failed status is not charged.

09 · Tips from the bench

Best practices for a webhook error object

  • Build a failure-reasons tile grouped by code for every campaign; it explains most delivery drops at a glance.
  • Map 131050 straight into your marketing suppression list, and 131026 into your SMS fallback queue.
  • Keep Meta's href with the stored error so agents can open the reference in one click.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms