Delivery Status and Error codes

A list of error codes that should be handled during integration.

Delivery Statuses

What are the different SMS statuses? What do they mean exactly?

There are four different SMS statuses, with ‘Delivered’, ‘Failed’, and ‘Rejected’ being final statuses for an SMS message.

  • Delivered - The SMS message was either delivered to the handset or accepted for delivery by the network operator.
  • Failed - The SMS message was not delivered.
  • Sent - The SMS message was sent but no final status is available.
  • Rejected - The SMS message was rejected, meaning that it was not accepted for delivery. Your account will not be credited for rejected messages.

For ‘Delivered’ messages, depending on the specific market, the SMS message was either delivered to the handset or accepted for delivery by the network operator.
P.S. Network-based delivery reports are mainly used in Southeast Asia and South America.

For 'Sent' messages, the SMS message was sent, but no final delivery status is available from either the handset or the network operator.
P.S. In some cases, SMS messages go through a retry cycle (standard retry cycle is 6 hours set by the operators), as they couldn't be delivered due to connectivity issues or were, in fact, already delivered but the delivery report is not available.

For ‘Rejected’ messages check ‘err’ values 004; 006; 007; 008 below.




HTTP Error Codes

Code Meaning
ERROR 101 Access is restricted, wrong credentials. Check the username and password values.
ERROR 102 Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103 Invalid IP address. The IP address you made the request from, is not in the API settings whitelist.
ERROR 104 Country was not found
ERROR 105 This country is not supported
ERROR 106 Invalid format provided - only json or xml is allowed
ERROR 107 Could not find the message with sms_unique_id
ERROR 108 Number is in blacklist.
ERROR 111 Sender parameter "from" is invalid. You have not activated this sender name on Messente.com
FAILED 102 No Delivery report yet, try again later.
FAILED 209 Server failure, try again after a few seconds or try the api3.messente.com backup server.

When SMS messages fail, what are the most common issues?

When SMS messages fail, we can investigate the reason behind the delivery issue by examining the error code.

Asynchronous Delivery Request "err" Values

Err Code Description
000 No error
001 General fatal error
002 Sending the SMS expired in 6 hours
003 Invalid number
004 ERROR crediting the Account
005 Could not determine the destination Country
006 Too many identical messages sent to the same number, blocked for 60 minutes
007 Sender name not allowed
008Number Blacklisted
999
 General temporary error 

001 - Failed to deliver the SMS message to this number

Messente has successfully forwarded the SMS message, but we received a response from the carrier that they are unable to deliver this message. 

Most common causes are as follows:
  • the number format is invalid
  • the handset is switched off
  • the number is deactivated or unallocated
  • operator-side error
  • signaling issues between the handset and the network operator
  • sender ID or a word in the message has been blacklisted by the local carrier(s)
  • sender ID has not been whitelisted by the local carrier(s)
  • sending messages to the given country has been disabled

In most cases, the exact reason needs to be determined manually.

Quick fix:

Restart the handset as it will reset the connection between the network operator and the handset, thus solving the issue 90% of the time.

002 - Sending SMS expired in 6 hours

The phone number format itself is correct but the message could not be delivered due to an unavailable network connection between the carrier and the handset. 

Possible causes:
  • the handset was switched off
  • the handset was out of coverage area
  • the handset itself is experiencing a temporary error and needs a restart

In this situation, the mobile operator pings the mobile phone every now and then to check whether the phone is able to receive the SMS. After 6 hours of unsuccessful attempts, the error code will be set to "expired".

003 - Invalid number

The phone number is invalid.

Possible causes:
  • invalid number format
  • the number is invalid and not reachable
  • the number contains the local country’s trunk prefix ‘0’
    e.g. +44 (0) XXXXXXXX

004 - Error crediting Account

The account has run out of prepaid credits.

005 - Could not determine the destination country/operator or invalid number format

The phone number format seems to be valid but there are no countries with this particular prefix.

Possible causes:
  • invalid number
  • the number is missing the area code/country prefix
  • the number contains local country’s trunk prefix ‘0’

006 - Too many identical messages sent to the same number, blocked for 60 minutes

Messente triggers a filter by restricting messages being sent to the same phone number.

Triggers are:
  • sending 5+ messages with identical content and sender ID within 60 minutes
  • sending 20+ messages to the same number with the same sender ID

Messente does this to prevent:
  • any unwanted message requests due to technical errors
  • our customer from sending too many identical messages to the end-customer
  • the end-customer from making too many SMS requests (e.g. requesting an unusually large amount of PIN codes)

For all of the above cases, the goal is to cut costs and protect the customer. The filter applies for 60 minutes starting from the 6th, or the 21st SMS message respectively.

P.S. This only applies to the affected phone numbers and not the account as a whole.

007 - Sender name not allowed

Cause:
  • using a sender ID that has not been whitelisted for your account

P.S. Whitelisted sender IDs are case sensitive, e.g. "CoffeeShop" is not the same as "coffeeshop" or "COFFEESHOP". They are all different for Messente. Incorrectly formatted sender IDs will be rejected.

008 - Number is in the ‘blacklist’

Cause:
  • the phone number is blacklisted in your account's phonebook and you can't send any SMS messages to that specific number

P.S. To remove a phone number from the blacklist, go to Messente Dashboard and navigate to the Phonebook (Contacts & Groups).

000 - No error