Introducing SMS error codes: Better Visibility into your SMS delivery

We are working continuously to provide better transparency to our customers and we’re happy to announce that we are taking another step in that direction. As of today, we will bring better clarity to SMS customers by providing detailed SMS error codes to every outbound SMS text message that fails to be delivered. These detailed error codes will help you to understand reasons for failure and troubleshoot issues right away with your outbound SMS deliverability.

What are SMS Error Codes?

Ever wondered what happens when an SMS is sent from your application to Plivo’s servers? First, we queue them up for sending them to our carriers at an appropriate rate that meets their compliance requirements and pass you the message_state “queued”. Then, upon successfully sending your text message to our carriers, we update the message_state to “sent”. And, once the text message is received by the destination carrier, we update the message_state to “delivered”.

This, of course, is the ideal scenario where everything works as it should. However, in systems involving multiple layers, such as working with multiple downstream carriers to deliver the SMS to the handset, errors can occur. And in those instances, we want to be sure to have an easy method to diagnose and ultimately resolve the issue. But all this must start at identifying the source of the problem, which is where SMS error codes come in.

SMS error codes are sent at each stage of the delivery process. Depending on the message_state returned, an accompanying error_code may be given. That is, if delivery is unsuccessful when we tried to deliver the SMS to the carrier, the message_state would update from “queued” directly to “failed” and an accompanying error_code will be given. If the message has been 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 either “undelivered”, which will also be accompanied by an error_code. In essence, SMS error codes can help you supplement your diagnosis of the delivery issues. Below is an illustration of the delivery success path and the message_states that can occur.

Process Diagram SMS Message States and Error Codes

If there are any issues with your SMS delivery, some of our carriers alert us with a delivery report that could include information about the failure. Currently, we work with carriers in hundreds of countries and unfortunately, each of them has a different method and frequency of reporting information about SMS failures. In reality, some carriers send error codes for nearly every undelivered SMS, while other carriers send error codes for less than 5% of undelivered text messages.

This occurs because there is no standard for reporting error codes and not all carriers support delivery reports. Meaning, we can’t control the delivery, quality, or frequency of delivery reports. However, for the error codes we do receive, we knew we could build a better model so that our customers can have a standardized method identifying potential delivery issues.

That’s why we went back to the drawing board, 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. That is, when a carrier reports an SMS error while trying to deliver your text message, it will be mapped to one of our standardized SMS error codes.

Now, for every SMS that you send through the Plivo platform, Plivo will return a message_state of “queued”, “sent”, “delivered”, “failed”, “undelivered”. And for messages that “failed” or were “undelivered”, an SMS error codes will be provided in the error_code parameter.

Both message states and error codes will be 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, you can also visit the SMS logs in your Plivo user interface under the Logs tab.

The following are SMS error codes that we have standardized. Going forward, whenever your text message does not reach its destination, you can 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 1600 for messages encoded with GMS and 737 for messaged encoded with Unicode. Note that while we provide a separate error code to indicate if 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, you can 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 have added systems and algorithms that detect spam content and then block them before they even get 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 US & Canada. Long codes are 10-digit phone numbers and are intended only for peer-to-peer (P2P) communication. If this issue persists, we highly recommend using short codes for sending bulk messages within US and Canada. Visit our short code page to learn more about obtaining and setting up a short code for your campaign.

However, if you are confident that your message content is compliant, then retry sending the message again. 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 is 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 (e.g., 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 is able to receive text messages. All phone numbers in your application should include country code, area code, and phone number without spaces or dashes (e.g., 14155555555). If you’re sending multiple text messages, make sure that the phone numbers are separated with the “<” character (e.g., 14156667777<14157778888<14158889999).
60 Loop detected The carrier is not able to route your SMS because certain settings in your application are corresponding to 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 to ensure that your applications do not trigger loops, it’s a good idea to create loop filters in your application because not all carriers have loop detection.

In some cases, this error code is returned when the carrier determines that it is impossible to route the SMS and the message has to be dropped as it is being looped between platforms.
70 Destination permanently unavailable The destination (i.e., “dst”) phone number is not active and there is no indication of when it will become available again. Note that 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 is 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 destination (i.e., “dst”) phone number is not reachable. Note that this is a broad error code and often times, the carrier does not indicate the reason for the destination to be temporarily unavailable. Though, possible reasons could be due to the handset being turned off or out of coverage. To resolve this, 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 was not available. Please note that carriers do not offer the reason for why the route is unavailable, but since this is typically a carrier issue, please contact us and include the message UUIDs of the SMS affected.
100 Prohibited by carrier The carrier rejected the text message because the network did not support the message being sent. This could occur if the destination network does not support SMS.
110 Message too long The message content exceeds the character limit of 1600 for GSM and 737 for UTF encoded messages. Note that depending on the byte size, Emoji characters can also increase the message character count significantly. Also, Plivo automatically concatenates messages longer than 160 characters for GSM encoded messages and 70 characters for UTF encoded messages. Check our FAQ 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 message replies with a opt-out keyword including “STOP”. All messages to destinations that have opted out will be blocked until the destination opts in with another response. Check our FAQ to learn more 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 United States Toll-Free phone number to a Canadian phone number destination. Unfortunately, carriers limit US Toll-Free phone numbers to only send SMS 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 cases, 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 have been affected.

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

Plivo provides error codes at 3 different levels to help you identify exactly where an error has 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 either than a “200” response, then 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 either “Undelivered”, this means that even though Plivo successfully delivered the SMS to the carrier, the carrier still failed to deliver your message to the destination. In the event of any failed message states, check the SMS error code for more details on the error. Remember, since not all carriers support delivery reports, some messages showing the “Sent” message_state could still have errors. Therefore, it’s safer to check your SMS error codes if issues persist.

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

If the above steps have been completed, and the SMS delivery issue persists, then the following reasons may be the culprit.

  • Check that you have 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. This is because our carriers send us delivery reports only if their destination carriers do the same. Therefore, if the destination carrier never responds back, then our carrier would not be able to provide a delivery report either.
  • Is the destination number in a Do Not Contact (DNC) list? A few countries (e.g., India) have a DNC list. Bound by consumer protection regulations, our carriers are not able to deliver messages to recipients who have opted in to DNC lists. If a recipient opts out of a DNC list, then text messages can be delivered normally.

If SMS delivery continues to be a problem despite having taking all the necessary precautions, please open a support ticket and we can help you identify the problem. Be sure to include message_uuids of the text messages affected (preferably messages from within the last 72 hours).

We’d love to hear from you, so please reach out to us at https://support.plivo.com/support with your feature requests and user feedback.

comments powered by Disqus