Transaction error codes

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.

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 — 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 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:

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 values instead.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Transaction error codes

Timeout errors

User action errors

Insufficient funds

Transaction status errors

System and internal errors

Account and recipient errors

Voucher errors

Payment method errors

Supported region errors

Default

​Timeout errors

​User action errors

​Insufficient funds

​Transaction status errors

​System and internal errors

​Account and recipient errors

​Voucher errors

​Payment method errors

​Supported region errors

​Default

Timeout errors

User action errors

Insufficient funds

Transaction status errors

System and internal errors

Account and recipient errors

Voucher errors

Payment method errors

Supported region errors

Default