How can I troubleshoot SMS delivery?

Questions:

  • How can I fix my SMS delivery?
  • What does this response code mean?
  • Why did delivery of my SMS fail?
  • Why did my SMS not deliver?

Answers:

Are the API requests being accepted by Nexmo? i.e. Is the initial response code successful (0)?

No:

Which error code has been returned? 

Some common examples are:

1 – Throttled – You are sending faster then your account allows you to send (by default 30 SMS/s; only 1 SMS/s/virtual number sender is allowed when sending to the US using a long virtual number)
2 – Missing params – You are missing a parameter in your http request. The obligatory parameters to send an SMS are: from, to, api_key, api_secret, text).
4 - Invalid credentials - Your API Key or Secret are incorrectly specified.
8 – Partner account barred – Your account has been suspended. You will need to contact us at support@nexmo.com.
9 - Partner Quota Violation - You do not have sufficient credit to complete your request. You will need to top up your account. Once you have, you should retry to send the message.
6 - Unroutable - We don't have reach to your destination. It may be a fixed line phone number or you didn't specify the country code.
14 - Invalid sender - Frequently seen when trying to use non-authorized senderID in North America, where a Nexmo long virtual number or short code is required.
29 – Non White-listed destination - This will occur when your account is in a demo mode and you haven’t added the number to your whitelisted destination list. Note that you may remove this limitation by topping up your account.

Yes:

In the case that Nexmo accepted the API request, we will have passed the request to our supplier or operator and any failure occurred downstream. Continue following this guide to debug the reason the SMS did not arrive

 

2) – Is the destination number a valid MSISDN?

Is the number valid and specified in the correct international format?

In many countries there is a difference between the local and the international format, or between SMS and voice calls. For instance, within the UK numbers should start with a 0, but when calling or texting the number in the international format, one must add the international prefix (44) and remove the leading 0.

Remember also that Nexmo will only accept MSISDN’s specified with international format. As such, one must include the international calling code prefix for each number.

Is the number still active and valid? If you are unsure if the number is valid, You could verify using our Number Insight API or in the dashboard.

 

3) – Are you using Delivery Receipts (DLR’s) as the unique indicator of delivery success or failure?

Yes:

Note that some countries will not support DLR's so a pending/missing Delivery Receipt may not necessarily indicate a failed delivery. Examples of countries without support for Delivery Receipts include Latin American countries, the US and Canada (when sending from a long virtual number). In many of these countries, you will not get a DLR, or you might get one inconsistently. This does not mean that the message did not arrive.

No. The handset owner has directly reported that the message did not arrive:

In this case, other factors might be affecting the delivery of the SMS, including those related to the country’s regulations and restrictions.

Some countries have strict Do Not Call lists in place (such as India) and therefore, only certain types of traffic are allowed, or at certain times of the day (such as France). There are many other different variables that may affect your traffic in each country, please check our full country specific articles () to help you understand what the issue could be.  

4) - I’ve checked the local regulations and I’m sending according to the rules and the number is valid. What now?

If none of the above apply it may be that failed delivery is due to issues such as:

Carrier Spam Filters

Most carriers in developed markets prefer to use regulations to control the flow of spam. In developing markets, however, technology is used to filter out unwanted texts. These filters, however, are not perfect and can lead to filtering legitimate SMS traffic, as well. Some filters even send back a fake handset delivery confirmation. You think your message is delivered, but it is  not. Furthermore, filter technology is in constant evolution, and associated algorithms change constantly. Keeping track of which carriers filter and how is a complex task.

Roaming

Unfortunately we cannot ensure delivery to roaming numbers due to the complexity and lack of reliability of Carrier Interconnection Agreements. Basically, this is related to the routing carrier not having Interconnection Agreements with the roaming operator.

Sending the Wrong Content

Not all phones support all languages. For instance, sending a Chinese message to a French phone will get to the handset but will not display to the user. Sending binary messages to an iPhone won’t work, either. Certain carriers also filter some keywords (such as the carrier’s own name) to prevent brand theft and scams. 

Handset Cannot Receive SMS

There are any number of reasons that can prevent a phone from receiving an SMS that it would be able to receive under normal conditions, including the phone being out of reach, a full memory, roaming, temporary disconnection, the number not existing anymore, and so on.

Portability Failure

A lot of phones get ported everyday from one network to another. The number will still look like the original network but the real network has changed. To address this, carriers have introduced network look-ups that provide them with the real network before sending the message. This guarantees that the SMS is routed correctly. The process, however, is not perfect. Network look-ups are expensive, and many providers don’t do them everywhere. Some carriers, in fact, still don’t even support these looks-ups at all. Additionally, some portability databases only get updated every 24 hours.

 

*************************

If, after going through these troubleshooting steps, you still do not have a clear reason for why your message was not delivered, then our dedicated support team would be happy to help resolve this issue for you. You can send an email directly to support@nexmo.com, or you can create a ticket via our Helpdesk - https://help.nexmo.com. When contacting us please include as many details as possible, such as Nexmo message ID or API key, destination number and timestamp.

 

Have more questions? Submit a request