> ## Documentation Index
> Fetch the complete documentation index at: https://api.tandapay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction errors

> Why charges and payouts fail, and what to tell the customer.

When a charge or payout fails after Tanda accepted it, the webhook shows `status: "failed"` and [Get transaction](https://api.tandapay.io/api-reference/endpoint/get-transaction.md) shows `chargeStatus: "failed"`. The reason is in `note`, or in `failureReason` on payout webhooks.

> [!WARNING]
>
> 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](https://api.tandapay.io/api-reference/endpoint/service-status.md) 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](https://api.tandapay.io/api-reference/endpoint/account-resolver.md) 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](mailto:ceo@tandapay.ke). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.