Transaction Error Codes

Timeout Errors

Error 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 payment charge expired before completion.
Payment request expired.	The payment request, payment link, virtual account, or channel session expired before completion.

Error Message	Description
The User could not be reached.	The mobile device was unreachable (off, out of service, etc.).
The user cancelled the request.	The user actively declined or cancelled the payment prompt.
The user did not authorize the transaction.	The user saw the prompt but chose not to authorize 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 payment flow but did not choose a channel.
The PIN entered is invalid or was not provided.	The customer entered an invalid PIN/OTP, skipped PIN entry, or the credential is locked.
The user has another active USSD session.	The customer already has an active USSD session and cannot start another one.

Error 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 has been hit.	Deposits

Error Message	Description
The user did not complete the transaction.	The operation finished on the 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. Wait before retrying.
The transaction was not completed.	The transaction started but was not finalized.
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.	The processor has accepted the request and the transaction is still pending or under processing.
Invalid transaction amount.	The amount is outside the processor's allowed range, has invalid decimals, or does not match the expected amount.
Invalid or missing transaction details.	Required transaction fields are missing, malformed, or failed provider validation

Error Message	Description
Connection was lost.	The connection to the upstream provider was unexpectedly closed.
Transaction failed due to internal processing issues. Please try again.	An internal processing error on the provider side. Retry recommended.
Transaction could not be completed in time. Please try again and approve within 5 minutes.	The provider could not process the transaction. Retry and approve promptly.
Transaction failed due to system error	A generic system-level failure on the 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 experiencing high load. Retry after a short delay.
Provider service is temporarily unavailable.	The upstream processor, network, or payment method is unavailable or returning service errors.
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 for the payment prompt.
Transaction authorization failed.	Processor authentication, authorization, merchant activation, or product assignment failed.

Error 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 on the provider side.
The recipient's number is invalid or not registered for Mobile Money.	The payee number does not exist or is not enrolled in Mobile Money.
The sender's number is invalid or not registered for Mobile Money.	The payer number does not exist or is not enrolled in Mobile Money.
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 submitted number does not match the format required by that provider or payment method

Error 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.

Error Message	Description
This card is not allowed for this transaction type.	The card cannot be used for the attempted transaction type.

Error Message	Description
Country `{countryCode}` is not supported.	The selected country is not supported for this transaction path, for example `Country GH is not supported`.

If the error does not match any known pattern, the API will return:

Unknown error occurred.