How to troubleshoot failed SMS delivery sent via HTTP API Request?

1. Has the SMS successfully reached Wavecell platform?

If NO:
Upon submitting the request, you can check the response returned. Some common errors are as follows:

1) Unauthorised or Invalid Credentials: The credentials are incorrect. Please ensure that you use the correct credentials in your Authentication Parameters:
- Username: Your Wavecell AccountID
- Password: Your Wavecell Password (this can be modified from your Account Dashboard)

2) The request is not properly authenticated. The most common errors are as follows:
a. The credentials are included in the message body payload.
b. There is no authorisation parameter or credentials included in the request.

- Credentials are required to be included in the "Authorisation Parameter". This can be added in your header. For exmaple:

PHP script:

$username = 'Account_id';
$password = 'Password123';
$header = array( 'Content-Type:application/json', 'Authorization: Basic '. base64_encode("$username:$password") );

Or if you are using cURL, include your credentials in the "-u" field :

curl -X "POST"
-u username:password
-H "content-type: application/json"
-d $'{
"source": "SMS",
"destination": "639xxxxxx",
"text": "test"

The credentials can also be passed directly in the API. This is the sample:


- Missing Parameters: You are missing a parameter in your HTTP request structure. The required parameters to send SMS are Destination number and message body.

- InternalServerError: Most likely, API is inaccesible at the time of request, timeout error, etc.

If YES, a MessageId has been returned which signified that Wavecell has proceeded with your request, and sent it to the Network Operator; any failure occurred downstream. This is continued as follows.

2. Is your account credit sufficient?

Failed delivery might also be due to insufficient credits in your account. Please ensure that you have enough credits before sending SMS. You can view your remaining credits through our Customer Portal.

3. Is the destination number active and valid?

Ensure that the destination number is a valid mobile number that is in service, reachable, not a landline, not a voip number, etc. The numbers should also follow the correct international format.

International format includes an international country code prefix which has to be added in local mobile numbers. Any numbers starting with "0" should be removed.

An example of a common mistake:

+63 (Philippines country code) added to local PH mobile number, the "0" should be removed. It should appear as 6309263794261 instead of 639263794261.

4. Are your successful or failure deliveries indicated through Delivery Receipts (DLRs)?

If YES, this means that some countries do not support DLRs. Therefore, a pending or missing Delivery Receipt may not necessarily mean a failed delivery. Such countries with no Handset DLR incudes: LATAM, US and Canada.

If NO, this means that the handset owner has confirmed that the message did not arrive.

The following factors are to be considered:

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. Certain carriers also filter some keywords (such as the carrier’s own name) to prevent brand theft and scams.

Handset Related Issue

There are various number of reasons that can prevent a phone from receiving an SMS that it would be able to receive under normal conditions. Some of the reasons are that the phone is 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 do not do them everywhere. Some carriers, in fact, still do not even support these looks-ups at all. Additionally, some portability databases only get updated every 24 hours.

5. Country’s regulations and restrictions related issue

The issues might be related to the country’s regulations and restrictions.

For instance, some countries have strict Do Not Call lists in place 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.


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


Please sign in to leave a comment.