> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerocash.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction error codes
> Why an individual charge or payout failed, and what to do about each case.
Zerocash normalises upstream provider errors into consistent, human-readable messages. These
appear in the `note` or `failureReason` field of a failed transaction — they explain why a
transaction that was *accepted* later *failed*.
For errors where the API call itself was rejected, see
[API error codes](/guides/errors/api-errors).
## Timeout errors
The customer or the provider ran out of time. Generally retryable with a fresh transaction.
| Message | Description |
| :--------------------------------- | :----------------------------------------------------------------------- |
| The user took too long to respond. | The STK Push prompt was sent but the user did not respond in time. |
| Request timed out. | The upstream endpoint did not respond within the allowed window. |
| No response from user. | The payment prompt was delivered but the user never acted on it. |
| Transaction time out. | A general timeout — the transaction or charge expired before completion. |
| Payment request expired. | The payment request, link, virtual account, or channel session expired. |
## User action errors
The customer declined, was unreachable, or entered something invalid. Not retryable without the
customer doing something differently.
| Message | Description |
| :---------------------------------------------- | :------------------------------------------------------------------ |
| The User could not be reached. | The mobile device was unreachable — off, out of service, and so on. |
| The user cancelled the request. | The user actively declined or cancelled the prompt. |
| The user did not authorize the transaction. | The user saw the prompt but chose not to authorise it. |
| The User cannot be reached by STK Push | The target number cannot receive STK Push requests. |
| The number is invalid. | The phone number provided is not a valid format. |
| The user did not select a payment channel. | The customer opened the flow but did not choose a channel. |
| The PIN entered is invalid or was not provided. | Invalid PIN/OTP, skipped entry, or a locked credential. |
| The user has another active USSD session. | The customer already has an active USSD session. |
## Insufficient funds
| Message | Description | Applies to |
| :------------------------------------------------ | :-------------------------------------------------------------- | :--------- |
| The balance is insufficient for the transaction. | The user's mobile money or wallet balance is too low. | Deposits |
| Low balance or payee limit reached or not allowed | The sender's balance is too low, or a payee-side limit was hit. | Deposits |
## Transaction status errors
| Message | Description |
| :-------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| The user did not complete the transaction. | The operation finished provider-side but no transaction was recorded. |
| STK Push Validation Failed | The STK Push request failed provider-side validation. |
| Duplicate transaction detected. Please wait 2 minutes before retrying | An identical transaction was recently submitted. |
| The transaction was not completed. | The transaction started but was not finalised. |
| Transfer to the specified shortcode is declined. | The target shortcode rejected the transfer. |
| Invalid transaction details. | One or more transaction parameters were invalid. |
| Transaction is being processed. | Accepted by the processor and still pending. |
| Invalid transaction amount. | The amount is outside the allowed range, has invalid decimals, or does not match what was expected. |
| Invalid or missing transaction details. | Required fields are missing, malformed, or failed provider validation. |
## System and internal errors
Provider-side problems. Most are worth retrying after a short delay.
| Message | Description |
| :------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
| Connection was lost. | The connection to the upstream provider closed unexpectedly. |
| Transaction failed due to internal processing issues. Please try again. | An internal error provider-side. Retry recommended. |
| Transaction could not be completed in time. Please try again and approve within 5 minutes. | The provider could not process it in time. |
| Transaction failed due to system error | A generic system-level failure provider-side. |
| Payment currently unavailable. Please try again later. | The payment method or provider is temporarily down. |
| Mpesa system is busy. | The M-Pesa platform is under high load. Retry after a delay. |
| Provider service is temporarily unavailable. | The upstream processor, network, or method is unavailable. |
| We did not receive a response from the mobile network. Please check your phone for an STK prompt or try again. | The mobile network did not return a callback. |
| Transaction authorization failed. | Processor authentication, merchant activation, or product assignment failed. |
Before retrying a batch of these, check
[Currency Uptime](/api-reference/endpoint/currency-uptime-checker) — if a corridor is degraded,
retrying immediately just produces more failures.
## Account and recipient errors
Almost always a bad account number or an unenrolled recipient. Fix the details before retrying.
| Message | Description |
| :----------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
| The initiator information is invalid. | The API initiator credentials or configuration are incorrect. |
| The customer does not exist. | The target customer account was not found provider-side. |
| The recipient's number is invalid or not registered for Mobile Money. | The payee number does not exist or is not enrolled. |
| The sender's number is invalid or not registered for Mobile Money. | The payer number does not exist or is not enrolled. |
| Invalid Phone Number | The phone number failed format validation. |
| Account does not exist. | The specified account could not be found. |
| Invalid mobile number. | The mobile number provided is not valid. |
| The number does not match the required format for the selected payment method. | The number does not match the format that provider or method requires. |
Run recipient details through
[Account Resolver](/api-reference/endpoint/account-resolver) before sending a payout. It catches
most of these before any money moves.
## Voucher errors
| Message | Description |
| :--------------------------------------- | :------------------------------------------------------- |
| The amount must equal the voucher value. | The transaction amount does not match the voucher value. |
| Invalid voucher. | The voucher is invalid or has already been used. |
## Payment method errors
| Message | Description |
| :-------------------------------------------------- | :---------------------------------------------------------- |
| This card is not allowed for this transaction type. | The card cannot be used for the attempted transaction type. |
## Supported region errors
| Message | Description |
| :---------------------------------------- | :------------------------------------------------------------------------------------------ |
| Country `{countryCode}` is not supported. | The country is not supported for this transaction path, e.g. `Country GH is not supported`. |
## Default
If the failure does not match any known pattern:
```text theme={null}
Unknown error occurred.
```
Never parse these strings to drive business logic — they are provider-normalised prose and can
change. Use them for logging, support tooling, and customer-facing messaging. Drive logic off
`status` and the [API `errorCode`](/guides/errors/api-errors) values instead.