Rate this page:

Debugging Common Issues with SMS

There are several common issues users run into when sending or receiving SMS messages. This guide outlines a few of the most common problems and provides troubleshooting tips:

My Message Wasn’t Delivered

There are several ways to troubleshoot an undelivered SMS message.

  1. Check your SMS logs for a record of the SMS request. If you don’t see a record of your message at all, the message likely encountered an error in your application or potentially with Twilio’s API.
  2. If the SMS isn’t in your logs and your application code is generating an error:
    • You can find some sample requests for sending SMS messages in your language of choice here on our documentation. These sample requests can help isolate any syntax issues that may crop up in your code.
  3. If you can't find the SMS in your logs and you received an error from Twilio:
    • If you received a 4XX response from Twilio’s API, Twilio encountered a problem and wasn’t able to send the message. You can look up the error code you received here.
  4. If the message is marked Undelivered or Failed in Twilio’s logs
    • In this case, Twilio received a delivery receipt from one of our carriers indicating that the message was not delivered. This can happen for several reasons, including carrier content filtering or availability of the destination phone.
  5. The message is marked Sent or Delivered in the logs but wasn’t sent to the device
    • To further debug, check out the section below for troubleshooting tips when a message doesn't arrive at your device.

I'm Not Receiving SMS Messages on my Twilio Phone Number

There are several questions you should ask if messages are not reaching your Twilio number:

  1. Do you have an SMS-enabled Twilio number? Does it have a webhook configured?
    • Log in to your Twilio account, navigate to the Phone Numbers section and click on ‘Manage Numbers’
    • Any number that shows the SMS icon can send and receive SMSes
    • If there is no icon under ‘SMS’, your Twilio number does not have SMS capabilities. Click on ‘Buy a Number’ to purchase an SMS-enabled Twilio number.
      Buy a SMS or MMS capable phone number
    • Your number also needs to have a URL associated with it to receive incoming SMS. You can set up this webhook the console for any Twilio phone number you own.
      SMS Webhook
  2. Are you expecting to receive SMSes from international numbers?
    • Some international carriers aren’t able to successfully pass off SMSes to Twilio’s network. Because of this, Twilio can’t ensure that international messages will always be received.
    • If you’re receiving domestic but not international SMS messages, we recommend contacting the international sending carrier for more information.
  3. Are you roaming or off your network?
    • Twilio cannot guarantee the deliverability of SMSes from roaming phone numbers. Twilio does not have the ability to determine whether or not the phone number you are sending SMS from is roaming at the time.
  4. Are you expecting to receive SMSes from a short code?
    • Short code carriers have arrangements to exchange messages with mobile phone numbers only, and Twilio phone numbers aren’t considered mobile numbers. Because of this, services like Google Voice, Facebook, and Skype, which use short codes (e.g., 55555) to send SMSes, will not be able to send messages to Twilio phone numbers.

To/From pairs violating blocked sender rules

You may see a response from Twilio about the message's From/To pair violating delivery rules when sending messages. The Twilio API returns this message if you attempt to send an SMS or MMS to a recipient who has previously replied STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, or QUIT to your Twilio number. You will not be charged for this message attempt.

When a user opts out of a phone number that belongs to a Messaging Service, they are also opted out of all messages sent from that particular Messaging Service.

To send messages to such recipients, the recipient must text START or YES to your Twilio number to opt in again.

Why do I Encounter Duplicate Messages?

The best way to begin debugging duplicate message issues is to review your message logs. You should look for a record for the message in question, as well as other messages that are duplicates that were sent within seconds of each other.

If you find duplicate messages sent within a few seconds of each other in your logs, it means that Twilio sent multiple messages to the carrier. This almost always means that Twilio received multiple POST requests from your application. Please check the HTTP request logs on your server to further investigate the requests you sent to Twilio.

Instances where Twilio’s system created a duplicate message without receiving a POST from your application are extremely rare. If you’ve checked your server logs and only see one request to Twilio, please let us know by contacting support with the SIDs of the duplicated messages.

If you find only one message in your logs, it means that Twilio sent just one message to the carrier and the duplication happened on the carrier's end. Users of all types of phones do occasionally receive duplicate messages, typically as the result of a safeguard carriers implement when they suspect there may have been a service disruption. Duplicate messages may also occur when the recipient is roaming.

If duplicate messages occur for an extended time over several different recipient carriers, please let us know by collecting the message records of the duplicated SMSes and contacting support.

My Messages are Delayed

To troubleshoot issues with delayed messages or other delivery issues, start by testing your numbers with the API Explorer. Create a message, filling out the From, To, and Body fields and any other relevant fields. Click ‘Make Request’ and keep the page open so you can examine the response later.

When you send a message via the API Explorer, one of three things will happen:

  1. The message arrives within 30 seconds
    • The problem with your messages most likely comes from your application code. Check that:
      • The "To" and "From" values you used in your code match those you used in the API Explorer.
      • Try using the code snippet generated in the API Explorer in your application and see if that fixes the issue.
      • Check your HTTP logs and verify the requests you made to Twilio did not result in 400 or 500 level errors.
      • 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 send.
  2. The message arrives more than 30 seconds later
    • SMS messages sent from Twilio typically arrive at their destination within 5 to 10 seconds, depending on the country and the carrier. If a message takes more than 30 seconds for delivery, we consider it 'delayed'.
      • Look in your SMS logs under ‘Delivery Steps’ to see more detailed timestamps, including when the request was created, how long it stayed queued on Twilio’s platform, and when we sent it to our carrier partner for delivery. This info provides insights to help you track down where latency may originate.
      • A large number of queued messages on the 'From' number may increase latency. See this article on Twilio’s rate limits for more information.
      • There may be congestion on downstream carrier networks. These problems usually resolve automatically when downstream traffic starts to clear.
  3. No message arrives
    • If the API Explorer generated a 201 response, check the following:
      1. Verify that the 'To' phone number:
        • Is valid and active.
        • Has good reception. If not, the message may just be delayed.
        • Can receive messages from other sources and senders.
        • Is not roaming internationally.
        • Is not on a ‘do not contact’ list.
        • Is not blocked by the carrier. If you are sending the message from a Twilio long code, try sending from a different Twilio long code. If the message is properly received, you’ve likely encountered a carrier’s volume threshold on your original long code. See this FAQ for more information.
      2. Try sending the message again. This is often the best way to verify the problem. If the message still doesn’t send, contact our support team with the SMS Message SIDs for each attempt that does not arrive. These SIDs are listed in the API explorer’s response.
    • If the API Explorer generated a 404 response Twilio was not able to send the message.
      • Any messages that return a 404 response should include an error code and a link to a detailed description of the error code. You can find information on all of our error codes here.

For building messaging applications at scale, we have a document of best practices to get you started in a way that minimizes latency and shows you how to monitor your messages with Messaging Insights.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more