Introducing SMS Error Codes: Better Visibility into Your SMS Delivery

16 Feb 2017

Plivo now provides detailed SMS error codes for every outbound SMS text message that fails to be delivered. These error codes can help you understand the reasons for delivery failures and troubleshoot issues with your outbound SMS messages.

Message states and SMS error codes

When you send an SMS message from your application to Plivo’s servers, we queue it up to send it to our carriers at an appropriate rate that meets their compliance requirements, and we pass your application the message_state queued. Upon successfully sending your message to our carriers, we update the message_state to sent. Once the destination carrier reports that it has received the message, we update the message_state to delivered.

This, of course, is the ideal scenario in which everything works as it should. However, in systems involving multiple layers, where messages may traverse multiple downstream carriers before delivery, errors can occur — and when they do, we wanted to have an easy way for our customers to diagnose and resolve any issues. That starts with identifying the source of the problem, which is where SMS error codes come in.

Plivo sends SMS error codes at each stage of the delivery process, depending on the message_state returned. That is, if delivery is unsuccessful when we tried to deliver a message to a carrier, the message_state will be updated from queued to failed and an accompanying error_code will be given.

If a message is successfully sent to the carrier, it can still hit roadblocks that can cause the SMS to fail. In this scenario, the message_state would change from queued to sent, then to undelivered, which is also accompanied by an error_code.

Here’s an illustration of the delivery path and the message_states that can occur.

Process Diagram SMS Message States and Error Codes

When there are issues with SMS delivery, some carriers alert us with a delivery report that may include information about the failure. However, we work with carriers in hundreds of countries, and each of them has a different method and frequency of reporting information about SMS failures. Some carriers send error codes for nearly every undelivered SMS, while others send them for fewer than 5% of undelivered messages.

Because there’s no standard for reporting error codes and not all carriers support delivery reports, we can’t control the delivery, quality, or frequency of error reporting. However, for the error codes we do receive, we wanted to build a model so that our customers could have a standardized way to identify delivery issues. To do that, we aggregated all the error codes from each carrier and mapped them to a set of error code categories that capture the entire spectrum of potential issues with SMS deliverability. Now, when a carrier reports an SMS error while trying to deliver your text message, it’s mapped to one of our standardized SMS error codes.

For every SMS message that you send through the Plivo platform, Plivo now returns a message_state of queued, sent, delivered, failed, or undelivered, and we provide an SMS error code in the error_code parameter when messages have failed or were undelivered.

Message states and error codes are sent to the callbackUrl set in your application. To retrieve the details of a specific message, make an HTTP GET request to the Message API with the message_uuid appended to the BaseURI. Alternatively, visit the Messaging > SMS Logs page of the Plivo console.

Here are the SMS error codes that we return. You can find an updated list of error codes in our documentation. Going forward, whenever your text message doesn’t reach its destination, refer to the SMS error code to identify the issue.

Error Code	Error Reason	Description
10	Invalid message	The message content is blank or exceeds the character limit of 1,600 for messages encoded with GMS or 737 for messaged encoded with Unicode. Note that while we provide a separate error code to indicate that a message is too long, some carriers only send an “invalid message” error and don’t differentiate between blank messages and long message errors.
20	Network error	The carrier delivering the text message had network issues. To resolve this, retry at a later time when the carrier network is unaffected.
30	Spam detected	One of the most common reasons for SMS delivery failure is carrier-level spam filters. Carriers use systems and algorithms to detect spam content and block it before it gets delivered. Unfortunately, these filters are always hidden, subject to carrier preferences, vary from carrier to carrier, and can be changed without notice. Another common reason why this error code could be returned is that you may have attempted to send too many messages using long code phone numbers in the US and Canada. Long codes are 10-digit phone numbers and are intended only for peer-to-peer (P2P) communication. If this issue persists, we recommend using short codes for sending bulk messages within the US and Canada. [Editor’s note 2021: Also consider 10DLC.] If you’re confident that your message content is compliant, retry sending the message. You can also contact our support team to whitelist your message one time with our downstream carriers.
40	Invalid source number	The source number you entered is either not in the correct format, not SMS-enabled, or not assigned to your Plivo account. Check the “src” phone number in your application and ensure that it’s in the correct format and has the ability to send text messages. All phone numbers in your application should include country code, area code, and phone number without spaces or dashes (for example, 14155555555 for US or +491155555555 for Berlin, Germany).
50	Invalid destination number	The destination number you entered is either not entered correctly, not SMS-enabled, or is a PSTN landline. Check the “dst” phone number in your application to ensure that it can receive text messages. All phone numbers in your application should include country code, area code, and phone number without spaces or dashes (for example, 14155555555). If you’re sending multiple text messages, make sure that the phone numbers are separated with the “<” character (14156667777<14157778888<14158889999).
60	Loop detected	The carrier cannot route your SMS because settings in your application set up an endless loop of messages being sent and received between your “src” and “dst” phone numbers. This can occur when two auto-responding SMS applications start to talk to each other and end up in a loop. Carriers detect loops by comparing messages within a predefined period of time to previous messages sent and received. SMS loops can increase unnecessary spend, so it’s a good idea to create loop filters in your applications, because not all carriers have loop detection. In some cases, this error code is returned when the carrier determines that it’s impossible to route the message, so it has to be dropped, as it’s being looped between platforms.
70	Destination permanently unavailable	The “dst” phone number is not active and there’s no indication of when it will become available. This is a broad error code where the carrier has not indicated the reason for the destination unavailability. Check the “dst” phone number to ensure that it’s correct. Also try sending messages to an alternative number to ensure that all other parts of your application are working.
80	Destination temporarily unavailable	The “dst” phone number is not reachable. This is a broad error code, and often the carrier doesn’t indicate the reason for the destination being temporarily unavailable. Possible reasons could include a handset being turned off or out of coverage. To resolve this error, retry your messages at a later time.
90	No route available	The carrier and fallback carriers were not able to deliver the SMS message because the route wasn’t available. Carriers don’t offer the reason why a route isn’t available, but since this is typically a carrier issue, you can contact us to find out on your behalf. Include the message UUIDs of the SMS messages affected.
100	Prohibited by carrier	The carrier rejected the text message because the network didn’t support the message being sent. This can occur if the destination network doesn’t support SMS.
110	Message too long	The message content exceeds the character limit of 1,600 for GSM-encoded and 737 for UTF-encoded messages. Certain characters can increase the message character count significantly. Plivo automatically concatenates messages longer than 160 characters for GSM-encoded messages and 70 characters for UTF-encoded messages. Check our FAQ post on long message concatenation for more details.
200	Source number blocked by STOP from destination number	The destination has opted out from your campaign and blocked all messages sent from your phone number. Opt-outs are typically received via text messages with an opt-out keyword of “STOP.” All messages to destinations that have opted out are blocked until the destination opts in with another response. See our FAQ posts about opt-out and opt-in processes.
201	Outbound messages from US toll-free numbers to Canadian destination numbers are blocked	Your application is attempting to send text messages from a US toll-free number to a Canadian phone number destination. Unfortunately, carriers limit US toll-free phone numbers to sending text message only to US phone numbers.
1000	Unknown error	Delivering your message failed for reasons that are unknown to us and to our carriers. If you notice too many of these, please open a support ticket with us so that we can help you identify the problem. Be sure to include the message UUIDs of recent messages (preferably within the last 72 hours) that were affected.

Troubleshooting SMS delivery using API response codes, message_states, and SMS error_codes

Plivo provides error codes at three levels to help you identify exactly where an error occurred. At the most basic level, the standard 200 HTTP status code provides the response to potential errors between your application and our API. If your application receives anything other than a 200 response, there’s likely a bug in your application.

Next, if your application receives a successful 200 HTTP status code, then it’s time to check your message_state. The message_state indicates where the error may have occurred. A Failed status means that your SMS was queued by our systems but failed to deliver to the carrier. If your message_state is Undelivered, then even though Plivo successfully delivered the SMS to the carrier, the carrier failed to deliver the message to the destination. In the event of any failed message states, check the SMS error code for details on the error.

Finally, since not all carriers support delivery reports, some messages that show the Sent message_state could still have errors, so check your SMS error codes if issues persist.

Troubleshooting SMS delivery using API response codes, message states, and SMS error codes

If SMS delivery issues do persist, try these actions.

Check that you’ve set the correct “src”and “dst” phone numbers. You could be successfully sending and receiving text messages to an incorrect phone number.
Is the destination number roaming outside of their local network? In a few cases, our carriers might not support international roaming. Our carriers send us delivery reports only if their destination carriers do the same, so if the destination carrier never responds back, then our carrier can’t provide a delivery report either.
Is the destination number in a Do Not Contact (DNC) list? A few countries (including India) have a DNC list. Because they’re bound by consumer protection regulations, our carriers cannot deliver messages to recipients who have opted in to DNC lists. If a recipient opts out of a DNC list, carriers can deliver text messages normally.

If you continue to have SMS delivery problems despite taking all the necessary actions, please open a support ticket so we can help you resolve the problem. Be sure to include message_uuids of the text messages affected (preferably messages from within the last 72 hours).