Troubleshooting SMS delivery failures can be stressful. In this help doc, we will explore all the possible reasons why an SMS sending or delivery might fail and provide corresponding troubleshooting steps.
How does SMS delivery work?
When an SMS is sent from the platform, it goes through various steps that can be illustrated as follows:
As you may have noticed, an SMS that you send to a contact goes through multiple layers. If there is a failed sending or delivery, it could indicate an error or filter at any of the mentioned layers.
Where can I find Sending/Delivery errors in the platform?
In most cases, when an SMS fails to send or deliver, we display an error in the conversation view that appears like this:
The error message and error code will provide you with clues about what is going wrong and how to proceed from there.
Possible reasons for failure
At the platform layer:
1. DND is enabled
When DND is enabled for a contact on the SMS channel or overall, the platform doesn't send the SMS and displays an error in the conversation screen.
2. Number is a landline number (Number validation)
When number validation is enabled, the platform checks if the contact's phone number is SMS-capable before attempting to send the SMS. If the number is not SMS-capable, the platform skips sending the SMS and shows an error in the conversations screen.
3. Account is new and undergoing ramped sending
For newly created accounts, the platform gradually increases the sending limits to prevent spamming or phishing. Administrators can choose to remove these restrictions if desired.
4. Account has exhausted the daily quota set by the administrator
Administrators can set a daily limit on SMS sending for each account. When the limit is reached, the platform skips sending SMS in bulk actions and automations. However, 1:1 SMS messages are still sent to allow clients to reply to their leads. Administrators have control over these limits for each account.
5. SMS sending privileges have been suspended due to a high error rate, opt-out rate, or carrier complaint rate
The platform monitors error rates, opt-out rates, and carrier complaint rates for all accounts to prevent spamming and phishing. If any of these thresholds are exceeded, SMS sending privileges for the account are suspended for a certain period. Any attempted SMS sending during this time will be skipped, and an error message will be displayed on the conversation screen.
At the Twilio/LC Phone Layer:
1. Number is on Twilio's DND list due to a previous opt-out or carrier complaint.
If the contact's number opted out from the Twilio number before, SMS will not be delivered unless the contact opted in by texting START to the Twilio number.
2. 30001 - Queue overflow
Twilio queues messages based on the sending rate of the sender or account. Messages can only be queued for up to 4 hours before they automatically fail. The queue length limit can be reduced by setting a lower Validity Period within your Messaging Service settings or API requests.
3. 30002 - Account suspended on the Twilio side
If your Twilio account is suspended between the time of message send and delivery, please contact Twilio or platform support (LC Phone). This failure occurs when your account was suspended after the message was queued but before it was sent by Twilio.
At Sender Carrier Network Layer:
1. 30003 - Unreachable destination handset
- The destination handset you are trying to reach is switched off or otherwise unavailable.
- The device you are trying to reach 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.
2. 30004 - Message blocked
- The destination number you are trying to reach is blocked from receiving this message.
- The device you are trying to reach does not have sufficient signal.
- The device cannot receive SMS (for example, the phone number belongs to a landline).
- The destination number is on India's national Do Not Call registry.
- There is an issue with the mobile carrier.
- You have sent a message from a US/CA Toll-free number to an end user handset that has previously responded with "STOP" or another opt-out keyword.
3. Attachment file size exceeded
4. Geo permission issues for international SMS
5. The body exceeds the limit of 1600 characters
- If you are using a trigger to send SMS, check the body of the message. Also, check to see if there is a custom value of {{message.body}}.
- For example, if someone replies via email and their email exceeds the limit of 1600 characters, the message will not send if you have the custom value {{message.body}}.
For more information on why a particular SMS failed, check out How to check logs for a specific text message in Twilio
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article