Troubleshooting WhatsApp

When a message cannot be sent over MessageBird's WhatsApp Business API, the status will change to “rejected” or “failed”, and any additional details available will be provided via an error object attached to the message that indicates the code and a description of the error.

The API response will look similar to this:

"id": "5f3437fdb8444583aea093a047ac014b",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"channelId": "853eeb5348e541a595da93b48c61a1ae",
"type": "text",
"content": {
"text": "This is a test WhatsApp message"
"direction": "sent",
"status": "failed",
"error": {
"code": 302,
"description": "The contact is not registered on WhatsApp."
"createdDatetime": "2018-08-28T15:52:41Z",
"updatedDatetime": "2018-08-28T15:52:58Z"

WhatsApp error codes for common delivery errors are listed below:

301The message failed to send. Please check your message is valid, including any media, and/or try again later.
302The contact is not registered on WhatsApp.
470Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid message template.


We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings