SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Troubleshooting Undelivered Messages

Issue

You've tried sending a 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.

Product

Programmable Messaging

Solution

Outbound message API requests 🔗

When Twilio receives an API request to send an outbound message, we return either a 201 Created response or a 400 Bad Request response. In either case, we create a record of the message in your logs with a corresponding status like "Delivered", "Undelivered" or "Failed", etc. You can check your Twilio project’s Programmable Messaging logs for the outbound message record via either Console, Messaging Insights or the REST API. If there was an error related to your message, there will always be an associated error code and message in the log.

Note, when using a Messaging Service to send messages, certain errors which would otherwise fail straight away with a 400 Bad Request response will instead be accepted initially and then assigned to a "Failed" message record later. See A note about error handling with Messaging Services below for details.

If you are seeing a large number of errors, you can 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 section 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, however, there can be other error codes that are returned in a 400 Bad Request response.

You can find all of the possible errors and their associated causes and solutions in our API Errors and Warnings Dictionary.

Messages marked "Failed" 🔗

The "Failed" message status indicates that Twilio was unable to send the message. This status is different from the "Undelivered" status, described below.

There will be an error code and message associated with the "Failed" message in your logs to help you resolve the issue. You can find all of the possible errors and their associated causes and solutions in our API Errors and Warnings Dictionary.

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 Logs, Messaging Insights or the REST API. Undelivered messages generally return a 3XXXX or 6XXXX error code, however there can be other error codes that are returned.

You can find all of the possible errors and their associated causes and solutions in our API Errors and Warnings Dictionary.

Messages marked "Sent" or "Delivered" 🔗

These message statuses 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 via the Try It Out section 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 through our Help Center Assistant.

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, what would normally be a 400 Bad Request response (such as 21610) will occur after the API request has been accepted, rather than being returned immediately as an API-level error.

This behavior difference is because Messaging Services handle API requests in a highly efficient 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 basic 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 message "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.

A message record will be created so you will be able to check the details of the failed message in your logs or Insights. You will not receive a Status Callback webhook.

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 Alphanumeric Sender ID.

Then, you make an API request to send from your Messaging Service SID to a US mobile number. Basic validation of the parameters show that 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 Alphanumeric 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.

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.

 

Have more questions? Submit a request
We can’t wait to see what you build.
Powered by Zendesk