You've tried sending an SMS 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 API Message Requests
When Twilio receives a valid API request to send an outbound SMS message, we return a
200 OK 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 SMS 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 incident, or an issue with with your API request.
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 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” or “Undelivered”
These message statuses indicate 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 SMS logs via either Console, or the REST API. A Failed or Undelivered message gerneally generally returns a 30XXX error code. Here are the most common problems we see:
Error 30008 "Message Delivery - Unknown error": The destination carrier has returned a generic error message.
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 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.
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 sent or delivered. The first step to troubleshooting this issue is to attempt to replicate the problems. 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 SMS logs from the last 24 hours that show these same issues, and Open a support request.