Any organization's ability to communicate effectively with both existing and prospective clients is essential to its success. Sending SMS has become a vital tool for most companies to communicate with their clientele. But just like with any other kind of communication, sending SMS can encounter errors and technical glitches.
In order to help you maneuver your way around handling errors when sending SMS, we have identified the thirteen (13) most common errors encountered and their respective possible causes and solutions.
1. US A2P 10DLC - Message from an Unregistered Number Error
Messages sent to US numbers will not be delivered if they are sent from numbers that are not associated with an approved A2P 10DLC Campaign.
Possible Cause/s | Possible Solution/s |
- You are sending messages to the US using a US 10DLC number that is not associated with an approved A2P 10DLC Campaign. | - Associate your US 10DLC number with a registered A2P Campaign by adding it to the corresponding Messaging Service via the Twilio Console or API. Alternatively, you can also use a different number that is already associated with an approved A2P Campaign to send messages in the US. |
For more information, kindly refer to Twilio’s detailed guide.
2. Unknown Destination Handset Error
The destination number you are trying to reach is unknown and may no longer exist.
Possible Cause/s | Possible Solution/s |
Aside from the destination number being unknown or no longer existing, it can also be because of the following: - The device you are trying to reach is not on or does not have sufficient signal. - The device cannot receive SMS (for example, if the phone number belongs to a landline). - There is an issue with the mobile carrier. | - Attempt to send another test message to this user via a REST API request, or through the API Explorer in the Twilio Console. |
For more information, kindly refer to Twilio’s detailed guide.
3. Unreachable Destination Handset Error
The destination handset you are trying to reach is switched off or otherwise unavailable.
Possible Cause/s | Possible Solution/s |
Aside from the destination headset possibly being switched off, other possible reasons may be: - The device you are trying to reach is not on or does not have sufficient signal. - The device cannot receive SMS (for example, the phone number belongs to a landline). - There is an issue with the mobile carrier. | - Attempt to send another test message to this user via a REST API request, or through the API Explorer in the Twilio Console. |
For more information, kindly refer to Twilio’s detailed guide.
4. Message Filtered Error
Your message content was flagged as going against carrier guidelines. Your message was filtered (blocked) by Twilio or by the carrier. This may be done by Twilio for violating Twilio’s Messaging Policy or Acceptable Use Policy, or by a wireless carrier for violating carrier rules or regulations.
Possible Cause/s | Possible Solution/s |
- Your message was identified as spam or unwanted messaging by Twilio's message filtering system. - Your message was flagged as objectionable and blocked by a wireless carrier. | - Ensure your messaging use case complies with Twilio's Messaging Policy and Acceptable Use Policy. - Review the information in How Does Message Filtering Work? to understand what causes filtering. - See How do I prevent my Twilio messages from being filtered (blocked)? for specific tips on avoiding message filtering. - If you believe your messages are compliant with Twilio and carrier policies, please collect 3 or more examples of Message SIDs that have the “undelivered” status with error 30007, and then contact Twilio’s Support team. |
For more information, kindly refer to Twilio’s detailed guide.
5. Landline or Unreachable Carrier Error
The destination number is unable to receive this message. Potential reasons could include trying to reach a landline or, in the case of short codes, an unreachable carrier.
Possible Cause/s | Possible Solution/s |
Aside from trying to reach an unreachable carrier, other reasons can be: - Your message was sent to a landline, or an unreachable carrier for this phone number type. | - Use the Lookup API to determine if the number is indeed a landline. If is not, try with an alternative phone number type. |
For more information, kindly refer to Twilio’s detailed guide.
6. Unknown Error
Possible Cause/s | Possible Solution/s |
If a message you sent is not delivered to the end device and returns as an error code, this means that delivery of your message failed for unknown reasons.
When Twilio receives a very generic error from their carrier partner that they have no further details about, they associate the message as an error, letting you know that they truly do not know what caused this error from the provider. | - Check that the phone you were sending to is turned on and can receive non-Twilio SMS - Ensure that the phone is not roaming off network. We cannot guarantee message delivery on roaming phones. - Try sending to other phones that have the same mobile carrier (you can use our Lookups API to determine the carrier if you’re unsure). If messages to other phones go through, the issue is likely device-related. Try rebooting the device or contacting the mobile carrier for help. - If you are sending SMS from an alphanumeric sender ID, see if using a Twilio phone number works better. We’ve observed that certain networks may block alpha sender IDs. - If the recipient number is another Twilio number, ensure that number has an action configured for its Messaging capabilities. Choose any available option like "Webhook" or "TwiML Bin." - Try sending a shorter message to the phone, with simple content that does not include any special characters. This would give our support team an idea as to whether the failure is related to concatenation or character encoding. - Twilio Support can help investigate what went wrong with our carriers. Please open a support request and include a minimum of 3 or more message SIDs where a 30008 error was thrown. Per our carriers' requirements, these SIDs can be no older than 48 hours at most. |
For more information, kindly refer to Twilio’s detailed guide.
7. MMS Not Supported by the Receiving Phone Number in this Region Error
Possible Cause/s | Possible Solution/s |
- If you received this error code on an inbound message, there was a failure attempting to receive an incoming MMS, as your Twilio phone number was sent an MMS in a region where Twilio does not support incoming MMS. - If you received this error code on an outbound message, the destination handset either doesn't support MMS, or MMS is not currently enabled on the device. | - For Inbound, it is recommended that you respond to the user sending the MMS to let them know that you cannot receive MMS in this region. |
For more information, kindly refer to Twilio’s detailed guide.
8. Attempt To Send To Unsubscribed Recipient Error
The person you are trying to message has opted out of receiving messages from your Twilio phone number, Channels sender, or Messaging Service.
You have attempted to message a 'To' number that has replied with "STOP" to one of your previous messages. You will not be able to send to the phone number specified in the 'To' parameter until the subscriber identified by the phone number has responded with "START".
Possible Cause/s | Possible Solution/s |
- The end-user handset has responded with "STOP" or another opt-out keyword. | - Consider removing this phone number from your list of recipients. - Request the recipient to resubscribe to your messages by texting "START" or another opt-in keyword to your Twilio sender. - Before sending messages to a recipient, ensure they have consented to receive messages from you. Please read these guidelines to understand messaging opt-in requirements and best practices. |
For more information, kindly refer to Twilio’s detailed guide.
9. US A2P 10DLC - Daily Message Cap Reached Error
Your messages to this particular carrier have exceeded the maximum allowable messages for the day. You have sent the maximum allowable daily messages for your brand to the carrier.
Possible Cause/s | Possible Solution/s |
- You have sent the maximum number of messages segments for the day. | - You must wait until the next calendar day to resume message sending. The day resets at 00:00 Pacific Time (US). Pacific time is affected by Daylight Savings Time and Standard Time switches. |
For more information, kindly refer to Twilio’s detailed guide.
10. Invalid Content Type Error
Twilio is unable to process the Content-Type of the provided URL. Please see Twilio's documentation on accepted content types for more information on valid Content-Types.
You must return a Content-Type for all requests. Requests without a Content-Type will appear in the Debugger as a 502 Bad Gateway error.
Possible Cause/s | Possible Solution/s |
- Having a phone number, outgoing call request or action attribute refers to a non-XML or audio resource. - Having a Play verb attempt to play non-audio content, such as XML or text. | - Verify that that your web server is returning a Content-Type and it is the expected value - Make sure the URL noted refers to a valid resource - Make sure messages to or from your Twilio phone number are using a supported content-type - Use one of the supported request types to call a Twilio function |
For more information, kindly refer to Twilio’s detailed guide.
11. Content Size Exceeds Carrier Limit Error
Message failed because the size of the content associated with the message exceeded the carrier limit.
Possible Cause/s | Possible Solution/s |
- Content size exceeding the carrier limit could be caused by to many characters or bytes in the message. UCS-2 encoded messages could have different limitations than GSM-encoded messages. | - Content size should be within carrier limits. - Message size should be within the carrier limits. |
For more information, kindly refer to Twilio’s detailed guide.
12. The Messaging Service Does Not Have a Phone Number Available To Send a Message Error
You have phone numbers or short codes in your Messaging Service, but none of them are capable of sending the requested message or media to this recipient. Possible causes vary depending on the type of message and the country of the destination number. Below are several common causes of this error.
Possible Cause/s | Possible Solution/s |
- You attempted to send a message to a United States or Canada mobile number, but you do not have any US/Canada numbers or short codes in your Messaging Service. US/Canada mobile numbers are not reachable from Twilio numbers from outside the US/Canada, due to limitations imposed by carriers. - You only have a short code number in your Messaging Service, and the recipient is not reachable from your short code (for example, the To number is from a different country than your short code, or is on a carrier that does not support short code messaging). - You attempted to send an MMS message, but you do not have any US/Canada long code numbers or an MMS-enabled short code in your Messaging Service. - You only have an Alphanumeric Sender ID in your Messaging Service, and the To number is in a country where Alphanumeric Sender ID is unsupported. - You attempted to send a message to a United States mobile number, but you do not have any 10DLC numbers that are registered with a verified A2P Campaign in the Messaging Service. Only numbers registered with a verified A2P Campaign can be allowed to send to US based numbers. | - Add a sender to your Messaging Service with the required capabilities using the Twilio Console or the REST API. |
For more information, kindly refer to Twilio’s detailed guide.
13. Numeric Sender ID Not Provisioned on Carrier
Provisioning Issue with Carrier You sent a message (message SID: SMXXXXX) to a mobile number in a country that requires Numeric Sender ID pre-registration and provisioning. The Numeric Sender ID is not currently provisioned with the carrier.
Possible Cause/s | Possible Solution/s |
- The Numeric Sender ID has not been provisioned by the carrier yet. Typically in this situation you would see >90% failures towards the carrier. - If this is for US A2P 10DLC and you just registered this number, it could take a brief period of time for all carriers to provision the number to your campaign. Typically you would see all messages towards a single carrier fail, if the code isn't provisioned. - Your shortcode has not been fully provisioned for production traffic, or the carrier has disabled your shortcode due to cancellation or compliance violations. Typically in this situation, you would see >90% failures towards the carrier. - The destination number has recently ported to a new carrier, and the port hasn't completed 100%. - Your toll-free number has not been fully provisioned for production traffic. | - If you believe your Numeric Sender ID should be registered, please collect 3 or more examples of Message SIDs that have the “undelivered” status error, and then contact Twilio’s Support team. |
For more information, kindly refer to Twilio’s detailed guide.