Transaction errors

When a charge or payout fails after Tanda accepted it, the webhook shows status: "failed" and Get transaction shows chargeStatus: "failed". The reason is in note, or in failureReason on payout webhooks.

Show these messages to your support team or customers, but don’t parse them in code. The wording can change. Use status to decide what happens next.

The customer didn’t respond in time

Start a new charge with a new externalReference.

Message	What it means
The user took too long to respond.	The customer didn’t act on the prompt before it expired.
No response from user.	The prompt arrived but the customer didn’t act on it.
Transaction time out. / Request timed out.	The transaction or upstream request expired.
Payment request expired.	The request, link or session expired.

The customer needs to do something

Don’t retry until the customer has fixed the problem.

Message	What it means
The user cancelled the request.	The customer declined the prompt.
The user did not authorize the transaction.	The customer saw the prompt and chose not to approve.
The User could not be reached.	The phone was off or out of coverage.
The User cannot be reached by STK Push	The number can’t receive a payment prompt.
The PIN entered is invalid or was not provided.	Wrong, skipped or locked PIN.
The user has another active USSD session.	The customer must close the other session first.
The number is invalid.	Fix the phone number format.

Not enough money

Message	What it means
The balance is insufficient for the transaction.	The customer’s wallet is too low. Ask them to top up or pay another way.
Low balance or payee limit reached or not allowed	The customer’s balance is low, or a limit applies.

Network or provider problems

Usually worth retrying after a short delay. Check Service status before retrying in bulk.

Message	What it means
Mpesa system is busy.	M-PESA is under heavy load.
Provider service is temporarily unavailable.	The network or processor is down.
We did not receive a response from the mobile network. Please check your phone for an STK prompt or try again.	No callback from the network. Ask the customer to check their phone.
Transaction could not be completed in time. Please try again and approve within 5 minutes.	Retry and ask the customer to approve promptly.
Connection was lost.	The upstream connection dropped.
Transaction failed due to system error	A generic provider failure.
Duplicate transaction detected. Please wait 2 minutes before retrying	An identical request was sent moments ago. Wait two minutes.

Recipient or account problems

Fix the details before retrying. For payouts, Account resolver catches most of these before money moves.

Message	What it means
The recipient’s number is invalid or not registered for Mobile Money.	The recipient isn’t on M-PESA or Airtel Money.
The sender’s number is invalid or not registered for Mobile Money.	The paying number isn’t registered.
Account does not exist.	The bank account wasn’t found.
Transfer to the specified shortcode is declined.	The paybill or till rejected the payment. Check the number.
Invalid transaction amount.	The amount is outside the allowed range.

Anything else

Message	What to do
Unknown error occurred.	Log the `transactionId` and contact support.

Get started

Accept payments

Send payouts

Webhooks

Go live

Transaction errors

The customer didn’t respond in time

The customer needs to do something

Not enough money

Network or provider problems

Recipient or account problems

Anything else

​The customer didn’t respond in time

​The customer needs to do something

​Not enough money

​Network or provider problems

​Recipient or account problems

​Anything else

The customer didn’t respond in time

The customer needs to do something

Not enough money

Network or provider problems

Recipient or account problems

Anything else