Troubleshooting Programmable Conversations

MessageBird offers multiple tools to help you to quickly understand any unexpected behavior between Programmable Conversations, the specific Channel, and your application.


MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).


errors[].codeintegerAn integer that represents the error type.
errors[].descriptionstringA human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameterstringThe parameter in your request related to the error if the error is parameter specific.

In the case of an error, the body of the response includes a json formatted response that tells you exactly what's wrong.

"errors": [
"code": 1001,
"message": "You are requesting with an invalid credential.",
"parameter": null

Message errors

When a message cannot be sent, the status will change to “rejected” or “failed”, and any additional details available will be provided via an error object attached to the message which indicates the code and a description of the error. Platform-specific error codes for common delivery errors are listed below.

"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 errors

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.

General API error codes

If you've received an error response and code from MessageBird that's not listed above, you can troubleshoot the error by exploring the general API Error Codes.

In case of an API error, the body of the response includes a json formatted response that tells you exactly what is wrong.


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