WhatsApp Platform Extended Error Codes
When a WhatsApp message fails, the error is reported at two levels of detail: the raw error code returned by the WhatsApp Cloud API (whose value is visible in the failure.source.code field) and a channel-agnostic Bird failure code (in the failure.code field) that groups the platform-specific error into a general category shared across all channels.
Exemple de code
"status": "delivery_failed",
"reason": "Unable to send WhatsApp message: facebook: (code: 131026, message: Message undeliverable, details: Unable to deliver message)",
"direction": "outgoing",
"details": "failure_subscriber",
"failure": {
"code": 15006,
"source": {
"name": "whatsapp",
"code": "131026"
}
},- failure.source.name is always whatsapp for messages sent over a WhatsApp channel.
- failure.source.code is the numeric error code returned by the WhatsApp Cloud API. It is the most specific piece of information available and maps directly to Meta's published list — see WhatsApp Cloud API error codes.
- failure.code is Bird's channel-agnostic Message Failure Code. The same Bird failure code can be produced by more than one WhatsApp code, and (as with other channels) the same Bird failure code is shared across platforms.
The above is a snippet; the actual message object returned contains the full set of fields.
WhatsApp codes that are not explicitly mapped below are reported with the Bird failure code UNKNOWN_FAILURE (15001), with the original WhatsApp code preserved in failure.source.code.
Bird Failure Code to WhatsApp Code Mapping
The following groups the WhatsApp Cloud API codes by the Bird failure code they resolve to.
INVALID_MESSAGE (12006)
The message was rejected by WhatsApp because a parameter was missing or invalid.
| WhatsApp Code | Meaning |
|---|---|
| 100 | Invalid parameter — one or more unsupported or misspelled parameters |
| 131008 | A required parameter is missing |
| 131009 | Parameter value is not valid |
INVALID_DESTINATION (14002)
The destination is not allowed to receive this message.
| WhatsApp Code | Meaning |
|---|---|
| 131021 | Recipient cannot be the sender (same phone number) |
INVALID_TEMPLATE (14003)
The message template is invalid, paused, or cannot be matched.
| WhatsApp Code | Meaning |
|---|---|
| 132000 | Parameter count mismatch (values did not match the template) |
| 132001 | Template does not exist in the specified language, or is not approved |
| 132005 | Hydrated (translated) template text too long |
| 132012 | Template parameter format mismatch |
| 132015 | Template is paused due to low quality |
INVALID_PERMISSION (15002)
The channel is missing a required permission, or its phone number needs (re-)verification before it can send.
| WhatsApp Code | Meaning |
|---|---|
| 133005 | Two-step verification PIN mismatch |
| 133006 | Phone number needs to be re-verified |
| 133008 | Too many two-step verification PIN guesses |
| 133009 | Two-step verification PIN entered too quickly |
| 133010 | Phone number is not registered on the WhatsApp Cloud API |
FAILURE_ENTITY_PROCESSING (15003)
WhatsApp accepted the request but could not process it afterwards.
| WhatsApp Code | Meaning |
|---|---|
| 131047 | Re-engagement message required (more than 24 hours since the recipient last replied) |
| 131052 | Media download error |
INVALID_PAYMENT (15004)
The message could not be sent because of a billing or eligibility issue on the WhatsApp Business account.
| WhatsApp Code | Meaning |
|---|---|
| 131042 | Business eligibility payment issue |
FAILURE_SUBSCRIBER (15006)
WhatsApp could not deliver the message to the recipient.
| WhatsApp Code | Meaning |
|---|---|
| 131026 | Message undeliverable — recipient is not a WhatsApp number |
UNSUPPORTED_ACTION (15008)
The requested message type or recipient is not supported.
| WhatsApp Code | Meaning |
|---|---|
| 131051 | Unsupported message type |
| 131062 | Business-Scoped User ID recipient not supported |
INVALID_SPAM (15011)
WhatsApp is throttling or blocking the message because of spam / rate-limiting to the recipient.
| WhatsApp Code | Meaning |
|---|---|
| 131048 | Spam rate limit hit (too many previous messages blocked) |
| 131056 | Too many messages sent to the same recipient in a short time |
INVALID_CAPACITY (15012)
The channel has reached a WhatsApp-imposed sending limit.
| WhatsApp Code | Meaning |
|---|---|
| 131049 | Meta chose not to deliver to maintain healthy ecosystem engagement (per-user marketing template limit) |
FAILURE_POLICY (15015)
The message was blocked for a policy violation.
| WhatsApp Code | Meaning |
|---|---|
| 132007 | Template content violates a WhatsApp policy |
OPTEDOUT_RECEIVER (15016)
The recipient has opted out of receiving messages from this business.
| WhatsApp Code | Meaning |
|---|---|
| 131050 | User has stopped receiving marketing messages from your business |
DELETED_PHONE_NUMBER_WHATSAPP (15018)
| WhatsApp Code | Meaning |
|---|---|
| 33 | Phone number has been deleted on WhatsApp Business |
RECIPIENT_UNDELIVERABLE (15019)
| WhatsApp Code | Meaning |
|---|---|
| 130472 | Recipient number is part of a Meta experiment; message not sent |
UNKNOWN_FAILURE (15001)
Returned for a generic user error and for any WhatsApp code not listed above. The original WhatsApp code is always preserved in failure.source.code.
| WhatsApp Code | Meaning |
|---|---|
| 135000 | Generic user error |
| (any other) | Unmapped WhatsApp error code |
Transient errors
Some WhatsApp codes indicate a temporary condition. Bird retries these internally, so they do not, on their own, produce a terminal failed status — a message only fails once retries are exhausted (typically surfacing then as MISSING_REPORT / EXPIRED, or UNKNOWN_FAILURE).
| WhatsApp Code | Meaning |
|---|---|
| 2 | API unknown / temporary outage |
| 3 | Internal error |
| 4 | API called too many times (rate limited) |
| 80007 | Business account rate limit hit |
| 130429 | Cloud API throughput rate limit hit |
| 131000 | Something went wrong (generic transient error) |
| 131016 | Service unavailable |
| 133004 | Server temporarily unavailable |
Full reference
A comprehensive list of the WhatsApp Cloud API codes Bird maps, the value they populate in failure.source.code, and the resulting Bird failure.code.
| WhatsApp Code | Meaning | Bird Failure Code |
|---|---|---|
| 33 | Phone number deleted on WhatsApp Business | 15018 DELETED_PHONE_NUMBER_WHATSAPP |
| 100 | Invalid parameter | 12006 INVALID_MESSAGE |
| 130472 | Recipient is part of a Meta experiment | 15019 RECIPIENT_UNDELIVERABLE |
| 131008 | Required parameter missing | 12006 INVALID_MESSAGE |
| 131009 | Parameter value is not valid | 12006 INVALID_MESSAGE |
| 131021 | Recipient cannot be the sender | 14002 INVALID_DESTINATION |
| 131026 | Message undeliverable (not a WhatsApp number) | 15006 FAILURE_SUBSCRIBER |
| 131042 | Business eligibility payment issue | 15004 INVALID_PAYMENT |
| 131047 | Re-engagement message required | 15003 FAILURE_ENTITY_PROCESSING |
| 131048 | Spam rate limit hit | 15011 INVALID_SPAM |
| 131049 | Meta chose not to deliver (marketing limit) | 15012 INVALID_CAPACITY |
| 131050 | User stopped receiving marketing messages | 15016 OPTEDOUT_RECEIVER |
| 131051 | Unsupported message type | 15008 UNSUPPORTED_ACTION |
| 131052 | Media download error | 15003 FAILURE_ENTITY_PROCESSING |
| 131056 | Too many messages to the same recipient | 15011 INVALID_SPAM |
| 131062 | Business-Scoped User ID recipient not supported | 15008 UNSUPPORTED_ACTION |
| 132000 | Template parameter count mismatch | 14003 INVALID_TEMPLATE |
| 132001 | Template does not exist | 14003 INVALID_TEMPLATE |
| 132005 | Hydrated template text too long | 14003 INVALID_TEMPLATE |
| 132007 | Template content violates a WhatsApp policy | 15015 FAILURE_POLICY |
| 132012 | Template parameter format mismatch | 14003 INVALID_TEMPLATE |
| 132015 | Template is paused | 14003 INVALID_TEMPLATE |
| 133005 | Two-step verification PIN mismatch | 15002 INVALID_PERMISSION |
| 133006 | Phone number needs re-verification | 15002 INVALID_PERMISSION |
| 133008 | Too many two-step verification PIN guesses | 15002 INVALID_PERMISSION |
| 133009 | Two-step verification PIN guessed too quickly | 15002 INVALID_PERMISSION |
| 133010 | Phone number not registered | 15002 INVALID_PERMISSION |
| 135000 | Generic user error | 15001 UNKNOWN_FAILURE |
For the full description of each WhatsApp Cloud API code, refer to Meta's WhatsApp Cloud API error codes. For the meaning of each Bird failure code, see Message Failure Codes.