Errors messages webhooks reference | Developer Documentation

Errors messages webhooks reference

Updated: Oct 22, 2025

This reference describes trigger events and payload contents for the WhatsApp Business Account messages webhook for errors messages.

Triggers

We are unable to process a request due to a system level problem.We are unable to process a request due to an app or account level problem.

Syntax

{
"object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "errors": [
              {
                "code": <ERROR_CODE>,
                "title": "<ERROR_TITLE>",
                "message": "<ERROR_MESSAGE>",
                "error_data": {
                  "details": "<ERROR_DETAILS>"
                },
                "href": "<ERROR_CODES_URL>"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Parameters

Placeholder Description Example value

<BUSINESS_DISPLAY_PHONE_NUMBER>

String

Business display phone number.

15550783881

<BUSINESS_PHONE_NUMBER_ID>

String

Business phone number ID.

106540352242922

<ERROR_CODE>

Integer

Error code.

130429

<ERROR_CODES_URL>

String

Link to error code documentation.

/docs/whatsapp/cloud-api/support/error-codes/

<ERROR_DETAILS>

String

Error code details.

Message failed to send because there were too many messages sent from this phone number in a short period of time

<ERROR_MESSAGE>

String

Error code message. This value is the same as the title property value.

Rate limit hit

<ERROR_TITLE>

String

Error code title. This value is the same as the message property value.

Rate limit hit

<WHATSAPP_BUSINESS_ACCOUNT_ID>

String

WhatsApp Business Account ID.

102290129340398

Example

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "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": "/documentation/business-messaging/whatsapp/support/error-codes"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}