You've tried sending an SMS or MMS message, but it didn't arrive. Fear not! This article is designed to help you walk through troubleshooting steps to diagnose, and hopefully fix, the problem.
- Outbound message API requests
- Messages marked "Failed"
- Messages marked "Undelivered"
- Messages marked "Sent" or "Delivered"
- A note about error handling with Messaging Services
Notice: We are planning improvements in Twilio's Error Logging Experience in 2024 which will affect the accuracy of logging behaviour for 400 Bad Response Errors mentioned in this article. See here for more information.
Outbound message API requests
When Twilio receives a valid API request to send an outbound message, we return a
201 Created response, and create a record of the message in your logs. To validate that we successfully received and processed your request, check your Twilio project’s Programmable Messaging logs for the outbound message record via either Console, or the REST API. If you aren't seeing a record of your message, then there was likely an issue with with your API request, or possibly a Twilio incident.
First, check the Twilio Status Page to see if an active incident could be causing your issues.
Next, try sending your message again, and check for similar results. You can send your message via a REST API request, or through the Try It Out feature in console. For an invalid request, Twilio returns a
400 Bad Request response, with an error code and message explaining what the issue is. This type of REST API error generally returns a 2XXXX error code. You can find the list of 2XXXX REST API errors along with instructions for resolving these issues in our API Errors and Warnings Dictionary.
Messages marked "Failed"
The "Failed" message status indicates that Twilio was unable to send the message. Twilio does not bill for "Failed" messages, because these never left Twilio's platform. This status is different from the "Undelivered" status, described below.
Messages marked "Undelivered"
The "Undelivered" message status indicates that Twilio has received a delivery receipt indicating that the message was not delivered. Check your message’s status and look for an error code in your Twilio project's Programmable Messaging logs via either Console, or the REST API. Undelivered messages generally return a 30XXX error code.
Please note, when using a Messaging Service to send messages, certain errors which would otherwise be API-level errors (described above under Outbound API Message Requests) will instead be assigned to a "Failed" message record. See A note about error handling with Messaging Services below for details.
You can find the list of 30XXX Messaging errors along with instructions for resolving these issues in our API Errors and Warnings Dictionary.
Messages marked "Sent" or "Delivered"
These message status indicate Twilio has received a confirmation indicating the message was sent, or a delivery receipt indicating the message was delivered. The first step to troubleshooting this issue is to attempt to replicate the problem. Attempt to send another test message to this user via a REST API request, or through the API Explorer in Console. Pay close attention to your request, and double check to verify you are attempting to send messages to the correct phone number in the correct E.164 format. If you see similar results, continue troubleshooting with the following checklist:
- Check the Twilio Status Page to see if an active incident could be causing your issues.
- Is the destination device powered on?
- Does the device have sufficient signal? If not power the device off, wait 30 seconds, and then power it back up.
- Is the device connected to the home carrier's network? We cannot guarantee message delivery on devices roaming internationally, or off-network.
- Can the device receive non-Twilio SMS?
- Can the device receive messages from another Twilio number (non-Alphanumeric Sender ID), or with a shorter one-segment (non-concatenated) body?
- Can other devices using the same mobile carrier receive your messages?
If you can rule out all of the above issues, Twilio's Support team can help investigate what went wrong with delivering your message. Please collect 3 or more Message SIDs in your Messaging logs from the last 24 hours that show these same issues, and open a support request.
A note about error handling when using Messaging Services
If you are using a Messaging Service to send outbound messages, instead of passing a specific "From" number or sender ID, Twilio's API behavior will be slightly different for some errors. Specifically, in some cases a 2XXXX series error (such as 21610) will occur after the API request has been accepted, rather than being returned as an API-level error.
This behavior difference is because Messaging Services handles API requests in a highly efficent way, which enables you to send more API requests in a short time. When you make a request to send a message using a Messaging Service, Twilio performs initial validation on your API request to ensure your parameters are valid. After the message record is created in our system, we perform a full validation, including choosing the best sender from your Messaging Service sender pool.
To illustrate this difference, consider two scenarios:
Scenario 1 – Passing a specific sender as your "From" parameter:
You make an API request to send a mesasge "From=MyCompany" and "To" a United States mobile number. Although MyCompany is a valid Alphanumeric Sender ID, that feature is not supported by carriers in the US. Twilio's API request validation will fail this request, and return
HTTP 400 Bad Request with error 21612.
No message record will be created when your API request fails, so you will not receive a Message SID.
Scenario 2 – Passing a Messaging Service SID:
You create a Messaging Service, and you add an Alphanumeric Sender ID called "MyCompany" to the sender pool. You do not add any Twilio phone numbers to the pool, only an Alpha Sender ID.
Then, you make an API request to send from your Messaging Service SID to a US mobile number. This is a valid API request, so Twilio will accept it by returning
HTTP 201 Created. The response will include a Message SID, which you can use to find the message in your Twilio Console or via the API.
After accepting your API request, Twilio will attempt to select a sender from your Messaging Service. Because you only added an Alpha Sender ID and you did not add any senders that can reach a US mobile number, Twilio will not be able to send the message. Twilio will mark the message record as "failed" with error 21703 ("The Messaging Service does not have a phone number available to send a message.")
Twilio will send this status update to you via your Status Callback webhook, assuming you have configured one on your Messaging Service or provided one in your API request.
As a reminder, messages with the "failed" status are not billed, and neither are API requests that return HTTP 400 – so, there is no cost difference in these different behaviors.