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.

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.

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.

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.

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.

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

Unknown error occurred.