A2P 10DLC Campaign Vetting Delays: Twilio cannot approve 10DLC Campaigns ourselves, and must rely on third parties who control our connections to carriers to sign off. These external processes are creating several week delays for our customers. We continue to escalate these issues and are working to reduce delays wherever possible. Further details will be shared in the Campaign Vetting Changes article as they become available.

Troubleshooting Undelivered Twilio SMS Messages

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.

Article contents:

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 API Explorer 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. Here are the most common problems we see:

Error 20003: Be sure that you are using the correct Account SID and Auth Token. Please note that using the Test Credentials will produce a response indicating that the message has been sent, but the message will not actually be sent.

Error 21408: You need to enable SMS permissions for this country on the Global SMS Permissions page.

Error 21606: You are attempting to use a "From" number which is not capable of sending SMS messages to your "To" number. Two common reasons for this:

  • You might be trying to send SMS from a phone number which is only enabled for voice. This list shows which Twilio phone numbers are SMS enabled. All other Twilio phone numbers are not capable of sending SMS messages.
  • You might be trying to send SMS from a number you have verified with Twilio. Twilio will only allow you to do this with phone calls, not SMS. You can learn more here.

Error 21610: You are attempting to send a message to a number that has opted out of receiving messages using a STOP keyword.

Error 21612. This error can have two explanations:

  • The carrier you are sending to is not a supported carrier. Twilio supports most carriers worldwide, but there are still carriers which we do not yet support. To determine if Twilio supports a particular carrier, please search for the country on the SMS Pricing page and scroll to the section labeled "All SMS Pricing for..." If the carrier does not appear on that list, Twilio cannot send SMS messages to that carrier at this time.
  • The "To" phone number is not properly formatted. We suggest all "To" numbers should use E.164 formatting to help ensure proper routing.

If your error is not listed here, 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.

The most common reasons for "Failed" messages are:

  • Error 30001 "Queue overflow:" you have exceeding the maximum queue length of your Twilio number or sender, or the message queued for longer than the ValidityPeriod you specified in your API request.
  • Error 30002 "Account suspended:" your Twilio account is currently suspended, for example due to running out of account funds and not having auto-recharge configured. When your account is suspended, Twilio will send you an email with the suspension reason. Check the email associated with your Twilio account for details.
  • (Specific to Twilio MMS media messaging) Error 11200, 11751, or 12300: These errors correspond to specific problems that can happen when Twilio attempts to retrieve media from the MediaUrl you provided to send an MMS media message. For example, a mismatch between the actual file type and the Content-Type header returned by the server would cause an MMS message to fail with error 12300.

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. Here are the most common problems we see:

Error 30005 "Message Delivery - Unknown destination handset": The destination carrier is reporting the To number is unknown, or no longer in service.

Error 30003 "Message Delivery - Unreachable destination handset": The destination carrier is reporting the 'To' number is unreachable - the device is likely powered down, out of the service area, or may not accept your messages.

Error 30007 "Message Delivery - Carrier Violation": The destination carrier is filtering out your messages for delivery.

Error 30008 "Message Delivery - Unknown error": The destination carrier has returned a generic error message.

Error 30004 "Message Delivery - Message blocked": Your message has been blocked from reaching the destination.

Error 30006 "Message Delivery - Landline or unreachable carrier": The destination is a landline phone, or the destination carrier can't be reached.

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.

If your error is not listed here, 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.

 

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