All Collections
Why did my messages Fail ?
Why did my messages Fail ?

Reasons why a message did not reach the clients handset.

Caroline Wavinya avatar
Written by Caroline Wavinya
Updated over a week ago

There are several stages to message sending and the message might fail at any of these. 

Stage 1: Running your Send SMS code

This is after you have set up your AT account, acquired a senderId or shortcode and integrated with our API. Once you've run your script. You get a response from our API. e.g: 

{'SMSMessageData': {'Message': 'Sent to 1/1 Total Cost: KES 0.8000', 'Recipients': [{'statusCode': 101, 'number': '+254705336634', 'cost': 'KES 0.8000', 'status': 'Success', 'messageId': 'ATXid_03cb5ecf11ce748794c0f9a85c276259'}]}}

This is the firsts stage a message might fail.  Below are some possible errors you might get and what they mean: 

Stage 2: The sent status

This is after your code has run successfully and you got the initial 'Success status from the API. And the status on your Dashboard(link) is 'sent' This means that your message has been delivered by Africa's Talking to the Telco and we are waiting on the Telco for the final status. 

Stage 3: Delivery Report

This is the final stage where we get a response from the Telco on whether the message got to the customers handset. 

Below are the final delivery reports: you might receive: 

  • Failed: The message did not reach the recipient’s handset. 

  • Rejected : The message has been rejected by the Telco. 

  • Submitted: The message has been sent to the Mobile Service Provider/Telco

  • Buffered : The message has been queued by the Telco

  • Success : The message has successfully reached the recipient’s handset

If the status is Failed/ Rejected it might be for one of the below reasons: 

  • DeliveryFailure: This occurs when message delivery fails for any reason not listed above or where the MSP didn't provide a delivery failure reason. On the sandbox this means that you may not be logged into the simulator, or the simulator is unreachable for some reason. 

  • InsufficientCredit : This occurs when the subscriber don't have enough airtime for a premium subscription service/message

  • InvalidLinkId : This occurs when a message is sent with an invalid linkId for an onDemand service

  • UserIsInactive : This occurs when the subscriber is inactive or the account deactivated by the MSP (Mobile Service Provider).

  • UserInBlackList : This would occur if the user has been blacklisted not to receive messages from a particular service (shortcode or keyword)

  • UserAccountSuspended: This would occur when the mobile subscriber has been suspended by the MSP.

  • NotNetworkSubcriber: This occurs when the message is passed to an MSP where the subscriber doesn't belong.

  • UserNotSubscribedToProduct: This is for a subscription product which the subscriber has not subscribed to.

  • UserDoesNotExist: This occurs when the message is sent to a non-existent mobile number.

  • Another reason that messages may fail to be sent is if they have the (%) percentage character in the text.

If none of the above failure reasons match your status, or if you were sending a message to another Telco, kindly send a sample number and time stamp of this to and we will look into it.

Did this answer your question?