Troubleshooting SMS Delivery


When sending SMS, the message is not delivered. Unsuccessful delivery may include an error code.

Applies To

  • Outbound SMS
  • Error Codes
  • Undelivered Messages


Error Code Indicating API Request Not Accepted by Vonage

Error Code Description Cause
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 Account Secret are incorrectly specified.
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, or you may have entered an invalid destination number.
8 Partner Account Barred Your account has been suspended. Submit a support request.
9 Partner Quota Violation You do not have sufficient credit to complete your request. Top up your account, then retry sending the message.
15 Invalid Sender Occurs when using a non-authorized Sender ID in North America, where a Vonage long virtual number or short code is required.
29 Non-White-Listed Destination Occurs when the account is in a trial period and you haven’t added the number to your whitelisted destination list. You can remove this limitation by topping up your account.

Message Not Delivered, Initial Response Code Successful (0)

In the case that Vonage accepted the API request, we will have passed the request to our supplier or operator and any failure occurred downstream. Review the following sections to determine the reason the SMS did not arrive.

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 Vonage will only accept MSISDNs specified with the international format. As such, one must include the international calling code prefix for each number.

Is the number active and valid?

If you are unsure if the number is valid, you can verify using our Number Insight API or in your Vonage API account dashboard.

Are you using Delivery Receipts (DLRs) as the unique indicator of delivery success or failure?

Yes: Some countries will not support DLRs, so a pending or 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 variables that may affect your traffic in each country. See our country-specific articles to help you understand what the issue could be.

I’ve checked the local regulations, 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.


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.

Additional Information

If, after going through these troubleshooting steps, you still do not have a clear reason for why your message was not delivered, submit a support request, and include as many details as possible, such as the message ID or API key, destination number, and timestamp.

Was this article helpful?
1 out of 3 found this helpful
Have more questions? Submit a request