The Cashless API normalizes upstream errors to provide consistent, human-readable messages.
| Error Message | Description |
|---|
| The user took too long to respond. | STK Push prompt was sent but user did not respond in time. |
| Request timed out. | Upstream endpoint did not respond within the allowed window. |
| No response from user. | Payment prompt was delivered but user never acted on it. |
| Transaction time out. | Transaction or payment charge expired before completion. |
| Error Message | Description |
|---|
| The User could not be reached. | Mobile device was unreachable (off, out of service, etc.). |
| The user cancelled the request. | User actively declined or cancelled the payment prompt. |
| The user did not authorize the transaction. | User saw the prompt but chose not to authorize it. |
| The User cannot be reached by STK Push | Target number cannot receive STK Push requests. |
| The number is invalid. | Phone number provided is not a valid format. |
| Error Message | Description | Applies To |
|---|
| The balance is insufficient for the transaction. | User's mobile money or wallet balance is too low. | Deposits |
| Low balance or payee limit reached or not allowed | Sender's balance is too low or a payee-side limit has been hit. | Deposits |
| Error Message | Description |
|---|
| The user did not complete the transaction. | Operation finished on provider side but no transaction was recorded. |
| STK Push Validation Failed | STK Push request failed provider-side validation. |
| Duplicate transaction detected. Please wait 2 minutes before retrying | Identical transaction recently submitted. Wait before retrying. |
| The transaction was not completed. | Transaction started but was not finalized. |
| Transfer to the specified shortcode is declined. | Target shortcode rejected the transfer. |
| Invalid transaction details. | One or more transaction parameters were invalid. |
| Error Message | Description |
|---|
| Connection was lost. | Connection to the upstream provider was unexpectedly closed. |
| Transaction failed due to internal processing issues. Please try again. | Internal processing error on provider side. Retry recommended. |
| Transaction could not be completed in time. | Provider could not process the transaction. Retry and approve within 5 minutes. |
| Transaction failed due to system error | Generic system-level failure on provider side. |
| Payment currently unavailable. Please try again later. | Payment method or provider temporarily down. |
| Mpesa system is busy. | M-Pesa platform experiencing high load. Retry after a short delay. |
| Error Message | Description |
|---|
| The initiator information is invalid. | API initiator credentials or configuration are incorrect. |
| The customer does not exist. | Target customer account not found on provider side. |
| The recipient's number is invalid or not registered for Mobile Money. | Payee number does not exist or is not enrolled in Mobile Money. |
| The sender's number is invalid or not registered for Mobile Money. | Payer number does not exist or is not enrolled in Mobile Money. |
| Invalid Phone Number | Phone number failed format validation. |
| Account does not exist. | Specified account could not be found. |
| Invalid mobile number. | Mobile number provided is not valid. |
If the error does not match any known pattern, the API returns:
Unknown error occurred.
