| Choice Error Code Mapping | Error Code | Description | Probable Root Cause |
|---|---|---|---|
| TXERR0001 Insufficient Balance | 1 | Insufficient Funds | Subscriber has declined using Overdraft aka Fuliza. The subscriber has insufficient funds on M-PESA. |
| TXERR0002 Invalid Account | 2 | Validation failed | The organization receiving the payment rejected it due to an invalid account number specified. |
| TXERR0011 Amount exceeds agreed limit | 3 | More Than Maximum Transaction Value | Transaction declined (invalid amount) |
| TXERR0015 Unknown Errors Occured | 4 | Would Exceed Daily Transfer Limit | Transaction declined. Daily transfer limit exceeded |
| '' (same as above) | 5 | Would Exceed Minimum Balance | Transaction declined (amount exceeds credit) |
| TXERR0020 Invalid Sender Party | 6 | Unresolved Primary Party | Transaction declined (invalid holder) |
| TXERR0021 Invalid Receiver Party | 7 | Unresolved Receiver Party | Transaction declined. (User/Account Number/ID unknown) |
| TXERR0031 Transfer to the specified shortcode is declined | 8 | Would Exceed Merchants Maximum Balance | Transaction declined. (merchants limit exceeded) |
| TXERR0022 Mpesa System Error | 9 | Transaction Processing Failed | M-pesa attempted to complete the transaction but was not successful |
| TXERR0023 Counterparty Account Not Registered on Mpesa | 10 | The MSISDN Provided is not registered on Mpesa | The user is not registered on M-pesa |
| TXERR0020 Invalid Sender Party | 11 | Debit Account Invalid | transaction declined (invalid Account holder) |
| TXERR0021 Invalid Receiver Party | 12 | Credit Account Invalid | transaction declined. (User/Account Number/ID unknown) |
| TXERR0020 Invalid Sender Party | 13 | Unresolved Debit Account | transaction declined (invalid holder) |
| TXERR0021 Invalid Receiver Party | 14 | Unresolved Credit Account | transaction declined. (User/Account Number/ID unknown) |
| TXERR0012 Duplicate Transaction Detected | 15 | Duplicate Detected | duplicate transaction |
| TXERR0015 Unknown Errors Occured | 17 | System external Failure | error on the external gateway (e.g. on the part of the Third party gateway, acquirer, etc) |
| TXERR0014 Transaction Format Mismatching | 20 | Unresolved Initiator | transaction declined. (invalid configuration data) |
| TXERR0999 System Error | 23 | The element SenderName is invalid | The IMT sender name does not have the mandatory two names |
| TXERR0024 Mpesa System Busy | 26 | Traffic blocking condition in place | |
| TXERR0025 Conflict of USSD Sessions | 1001 | Unable to lock subscriber, a transaction is already in process for the current subscriber. | Duplicated MSISDN, MSISDN has an existing USSD session. Conflict of sessions. The user has an ongoing USSD Session. USSD services are barred for user. |
| TXERR0026 Transaction Timeout | 1019 | Transaction has expired | The transaction has taken a long time before being processed within the allowed time limit |
| TXERR0024 Mpesa System Error | 1025 | An error occurred while sending a push request | System error. Please retry later. |
| TXERR0027 STK Prompt Time Out | 1032 | Request Cancelled By User. STK Prompt timed out waiting for user input | STK Prompt Cancelled by user |
| TXERR0028 The User cannot be reached by STK Push | 1037 | DS Timeout - The user does not have an updated SIM card or Mobile Phone is offline | User has an outdated SimCard or Phone is offline The user can not be reached by stk push |
| TXERR0029 STK Push Validation Failed | 2001 | The initiator information is invalid. | The user initiating the push has given invalid password input. The user has entered the wrong pin to validate the STKPUSH request. |
| TXERR0999 System Error | 2007 | External validation failed for the C2B transaction | This means the destination paybill has rejected the transaction as the sub-account number specified was not found in the destination (core) system. |
| TXERR0027 STK Prompt Time Out | 2026 | The channel session ID has expired. | The stk session has timed out due to a network disruption on the telco side. |
| TXERR0999 System Error | 2028 | The request is not permitted according to product assignment | The paybill only allows incoming transfers from MSIDN and not from other shortcodes (does not accept B2B transfers) |
| TXERR0030 Wrong Pay Type Specified | 2029 | Failed due to an unresolved reason type. | An attempt was made to transfer funds to a paybill while the request had specified a Pay till. An attempt to transfer to a Buygoods till when the request had specified transfer to a Paybill |
| TXERR0999 System Error | 2033 | The transaction receipt number cannot be found by the specified OriginatorConversationID or ConversationID | An attempt was made to query a transaction status using a reference that is not on the mpesa system. This occurs when either the original conversation ID is incorrect, or mpesa did not receive the original transaction request. |
| TXERR0023 Counterparty Account Not Registered on Mpesa | 2040 | Credit Party customer type (Unregistered or Registered Customer) can't be supported by the service | An attempt to transfer to a mobile number which is not registered/subscribed to receive Mpesa money |
| TXERR0031 Transfer to the specified shortcode is declined | 2043 | This organization is not a child organization of the initiator. | You are not allowed to transfer money to this Paybill shortcode |
| TXERR0999 System Error | 2080 | Amount will exceed M-PESA limit | For mpesa wallet, say the maximum limit allowable is 500k, if a transfer attempt will exceed that limit, the transfer will be rejected and the error 2080 returned. |
| TXERR0999 System Error | 400.002.02 | Bad Request | transaction declined (format error) |
| TXERR0999 System Error | 400.002.05 | Invalid Request Payload | transaction declined. (format error) |
| TXERR0999 System Error | 404.001.01 | Resource not found | error on the external gateway (e.g. on the part of the bank, acquirer,...) |
| TXERR0999 System Error | 404.001.03 | Invalid Access Token | authorization failed. Invalid Access Token |
| TXERR0999 System Error | 404.001.04 | Invalid Authentication Header | authorization failed. Invalid Auth Header |
| TXERR0034 Mpesa Service Unavailable | 500.001.1001 | Server Error | error on the external gateway (e.g. on the part of the bank, acquirer,...) |
| TXERR0034 Mpesa Service Unavailable | 500.002.02 | Error Occured Spike arrest Violation | Error Response from the connector/acquirer |
| TXERR0034 Mpesa Service Unavailable | 500.002.1001 | "Service is currently under maintenance. Please try again later | M-pesa is currently un available |
| TXERR0032 Disabled / discontinued shortcode | SFC_IC0003 | The operator does not exist. | The Paybill/Paytill shortcode is no longer available or has been discontinued/disabled |
| TXERR0002 Invalid Account | C2B00012 | Account does not exist in CBS | The organization receiving the payment rejected it due to an invalid account number specified. |
| TXERR0006 Counterparty Agent Not Responding | SVC0001 | Time out | The organization receiving the payment did not respond in a timely manner to a request to validate the account number from M-pesa. Mpesa automatically cancelled the transaction. |
| TXERR0002 Invalid Account | C2B1016 | Till not found and paymentRef is not an account | The account number specified was neither a valid account number nor a Till/short number. Invalid reference number encountered. |
| TXERR0002 Invalid Account | C2B1012 | Customer validation Failed | The organization receiving the payment rejected it due to an invalid account number specified. |
| TXERR0033 Counterparty Rejects Prepaid Account Transfers | C2B00012 | Prepaid Account is not Allowed | Only Post paid account are allowed to make the transfer |
| Choice Error Code Mapping | Error Code | Description | Possible root cause |
|---|---|---|---|
| TXERR0006 Counterparty Agent Not Responding | AB05 | Timeout at the Creditor Agent | Receiving participant's connection is down Network intermittency Participants Pesalink middleware is down Receiving participant's carrying out system maintenance Receiving participant's application is down hence cannot receive requests or cannot sent out responses Participants connection is down |
| '' (same as above) | AB06 | Timeout at the Instructed Agent | Receiving participant's application is down hence cannot receive requests or cannot sent out responses Receiving participant's carrying out system maintenance |
| '' | AB07 | Offline Agent | Participant carrying out system maintenance Participants connection is down |
| '' | AB08 | Offline Creditor Agent | Receiving Participants connection is down Participant carrying out system maintenance Creditor agents application is down hence cannot receive requests or cannot sent out responses |
| '' | NOAS | No answer from beneficiary | Participant carrying out system maintenance Participants connection is down Creditor agents application is down hence cannot receive requests or cannot sent out responses Network intermittency |
| TXERR0007 Counterparty System Not Available | AB09 | Error at the Creditor Agent. Reject | Transaction process aborted due to an error at the participant's end. The participant system is not available to accept the incoming transaction |
| '' | AG11 | Creditor Agent suspended from the Real Time Payment system | Receiver institution is suspended on the IPS |
| '' | RR04 | Regulatory reason | NULL |
| TXERR0008 Counterparty Bank Not Supported on Pesalink | CNOR | Creditor agent is not registered under this ID in the IPS | Receiving institution code is invalid/not registered on the IPS |
| '' | RC01 | Participant identifier incorrect | Institution code is invalid/not registered on the IPS. |
| TXERR0009 Original Transaction Not Found | AG09 | Original payment never received | The IPS never received the original request that the investigation message refers to. |
| '' | NOOR | No original transaction received | The investigation message identification is wrong or the IPS never received the original request that the investigation message refers to |
| TXERR0001 Insufficient Balance | AM04 | Insufficient funds | Debtor account does not have sufficient funds to warrant a debit on their account |
| TXERR0002 Invalid Account | AC01 | Account identifier invalid or does not exist | Receiving participant's core banking system unavaialable Account does not exist on the receiving participant's CBS |
| TXERR0003 Closed Account | AC04 | Closed account number | Account number has been closed by the Participant |
| TXERR0004 Blocked Account | AC06 | Blocked account | Account restricted in core Participating system due to various reasons Account number has been blocked by creditor |
| TXERR0005 Beneficiary Deceased | MS02 | Reason not specified | Transactions fails to honor the transaction and does not give the specific reason for the failure |
| TXERR0010 Amount is less than agreed limit | AM01 | Zero amount | Minimum amount that can be transferred through Pesalink is Ksh.1 |
| '' | AM06 | Amount is less than agreed minimum | Minimum amount that can be transferred through Pesalink is Ksh.1 |
| TXERR0011 Amount exceeds agreed limit | AM02 | Amount exceeds the maximum authorized amount | Maximum amount that can be transferred through Pesalink is 999,1000 |
| '' | AM14 | Amount exceeds agreed limit | Maximum amount that can be transferred through Pesalink is 999,999 |
| TXERR0012 Duplicate Transaction Detected | AM05 | Duplication | Participant system error resulting in duplicated requests |
| '' | DUPL | Duplicate payment | Participant system error resulting in duplicated requests |
| TXERR0013 Participant Systems Error | XT79 | Debtor Agent is not allowed to send pacs.008, pscs.028, camt.056 and receive NRR and PRR | Debtor is disabled from sending the type of request it is passing to the IPS |
| '' | XT80 | Creditor Agent is not allowed to receive pacs.008, pacs.028, camt.056 and send NRR and PRR | Creditor is disabled from sending the type of request it is passing to the IPS |
| TXERR0014 Transaction Format Mismatch | AM11 | Currency is invalid or missing | The only transaction type supported by IPSL switch is KES |
| '' | AM12 | Amount is invalid or missing | Amount field is either not captured, or is the format used is wrong |
| '' | AM18 | Number of transactions is invalid or missing | Number of transactions stated in a bulk file header should match the total number of requests |
| '' | DT02 | Invalid creation date | Wrong creation date when actual payment was created The date format is invalid |
| '' | RR01 | Missing debtor account or identification | Request/Response from Participant is missing the Cdtr/Dbtr account tag for send to account or Request/Response from Participant is missing the phone number tag for send to phone/wallet |
| '' | RR02 | Missing debtor name or address | Request/Response from Participant is missing the debtors name and address |
| '' | RR03 | Missing creditor Name or address | Request/Response from Participant is missing the creditors name and address |
| '' | XT06 | Invalid acceptance time | The date/time format sent in the request/response message is wrong or not recognized by the IPS |
| '' | XT13 | Unsupported XML field | Participant sent a tag that IPSL Switch does not conform to IPSL standards |
| '' | XT33 | Invalid data format | Participant sent a tag to IPSL Switch that does not conform to IPSL standards |
| '' | XT77 | Original amount mismatch | Amount in credit transfer request / payment initiation request, not matching the amount in the response |
| '' | AM09 | Wrong Amount | Participant system error resulting in mismatch in amount sent |
| TXERR0015 Unknown Errors Occured | MS02 | Reason not specified | Transactions fails to honor the transaction and does not give the specific reason for the failure |
| '' | CUST | Beneficiary decision without any reason specified | Participants middleware received a response that it cannot decipher, from the Core Banking orParticipant declined the request without specifying the exact reason for failure |
| TXERR0016 Multiple Transfers Declined by Velocity Checks | TE05 | Declined by switch rules | Transaction rejected due to velocity checks that do not allow the debtor/creditor to send/receive multiple transactions within a specified period of time |
| TXERR0017 Transaction Declined due to Irregular Narration | TE06 | Credit transfer rejected due to the rejection of the related initiation message | The payment initiation request was rejected by Debtor agent either due to Message tags in the request that the participant did not expect The account holder (initiating party) is not allowed by the debtor agent to send a payment initiation request |
| TXERR0999 System Error | AG10 | Agent suspended from the Real Time Payment system | Sender institution is suspended on the IPS |
| '' | AM23 | Amount exceeds settlement limit | Participant has depleted the available set base liquidity value |
| '' | XT87 | Inconsistent instructing agent | PIC captured in the instructing agent tag of request/response does not match the one configured on the IPS |
| '' | FF08 | End to End identifier is missing or invalid | The EndtoEndID is missing it the request/response from the participant |
| '' | MD01 | No mandate / Invalid Mandate | The mandate tag has been populated but its value has not been captured |
| '' | TE04 | Multiple Different Debtor Agents | Multiple PICS captured in the request/response |
| '' | TE01 | Timeout at the Debtor Agent | |
| TXERR0018 Transaction to the Account is Declined | AG01 | Transaction forbidden on this type of account | Account restricted in core Participating system due to various reasons |
| TXERR0019 Pesalink Service Unavailable | TECH | Technical problems resulting in erroneous transactions |
| Error Code | Description |
|---|---|
| TXERR0001 | Insufficient Funds |
| TXERR0002 | Invalid Account (Number) |
| TXERR0003 | Closed Account |
| TXERR0004 | Blocked Account |
| TXERR0005 | Beneficiary Deceased |
| TXERR0006 | Counterparty Agent Not Responding |
| TXERR0007 | Counterparty System Not Available |
| TXERR0008 | Counterparty Bank Not Supported on Pesalink |
| TXERR0009 | Original Transaction Not Found |
| TXERR0010 | Amount is less than agreed limit |
| TXERR0011 | Amount exceeds agreed limit |
| TXERR0012 | Duplicate Transaction Detected |
| TXERR0013 | Participant Systems Error |
| TXERR0014 | Transaction Format Mismatch |
| TXERR0015 | Unknown Errors Occured |
| TXERR0016 | Multiple Transfers Declined by Velocity Checks |
| TXERR0017 | Transaction Declined due to Irregular Narration |
| TXERR0018 | Transaction to the Account is Declined |
| TXERR0019 | Pesalink Service Unavailable |
| TXERR0020 | Invalid Sender Party |
| TXERR0021 | Invalid Receiver Party |
| TXERR0022 | Mpesa System Error |
| TXERR0023 | Counterparty Account Not Registered on Mpesa |
| TXERR0024 | Mpesa System Busy |
| TXERR0025 | Conflict of USSD Sessions |
| TXERR0026 | Transaction Timeout |
| TXERR0027 | STK Prompt Time Out |
| TXERR0028 | The User cannot be reached by STK Push |
| TXERR0029 | STK Push Validation Failed |
| TXERR0030 | Wrong Pay Type Specified |
| TXERR0031 | Transfer to the specified shortcode is declined |
| TXERR0032 | Disabled / discontinued shortcode |
| TXERR0033 | Counterparty Rejects Prepaid Account Transfers |
| TXERR0034 | Mpesa Service Unavailable |
| TXERR0035 | Abnormal Account Status |
| TXERR0999 | System Error. Retry. |
| Response Code | Description |
|---|---|
| 0 | Accept the service request successfully. Indicates that the request has passed basic validation tests and been passed on to the M-pesa system for processing. |
| 1000 | System is busy, the service request is rejected. Means the request has not been accepted, you can proceed by retrying. |
| 1001 | Caller authentication error. |
| 1002 | Parameter missing or data type error. |
| 1003 | Duplicate originator conversation ID. |
| 1005 | The element is invalid. |
| API | RESPONSES FOLLOW |
| 401 | Invalid Access Token - Using a wrong or expired access token |
| 400 | Bad Request – Invalid request payload. |
| 404 | Resource not found - The requested resource could not be found. |
| 405 | Method Not Allowed – B2C API is a POST |
| 500 | Internal Server Error – Server Failure |
| 0 | Process service request successfully. |
| 2000 | Service code error. |
| 2001 | Initiator authentication error. |
| 2002 | Receiver invalid. |
| 2004 | Amount invalid. |
| 2006 | Balance insufficient. |
| 2007 | Conversation ID invalid. |
| 2010 | Request has been rejected by the approver. |
| 2011 | Request process expired because of approval timeout |
| 2036 | One and only one of the query parameters ReceiptNumber, OriginatorConversationID and ConversationID can appear at the same time. |
| 2051 | The entered mobile number is out of the valid number segment. |
| 2052 | KYC field invalid. |
| 2015 | The TransactinID does not match the short code of ReceiverParty. |
| 2033 | The transaction receipt number cannot be found by the specified OriginatorConversationID or ConversationID. |
| 2069 | The IMT validation transaction (Partner Transaction ID) does not exist. |
| 2070 | The M-PESA transaction ID in the transfer request is inconsistent with the M-PESA ID in the validation request. |
| 2071 | Transaction already exists (Partner Transaction ID or M-PESA ID already exists). |
| 2072 | Duplicate IMT Money Transfer Request. Transaction already submitted. |
| 2073 | The Recipient in the Money Transfer Request is different from the Recipient in the Validation Request. |
| 2040 | Customer is not registered {Service only supports registered customers.}. |
| 2080 | The transaction failed as the daily, monthly or yearly authorized limit would be exceeded. |
| 2081 | The IMT transaction has been cancelled due to failed AML Screening. |
| 2082 | The IMT money transfer transaction(request) has expired. |
| Response Code | Response Message |
|---|---|
| 00000 | Completed successfully |
| 10000 | System error |
| 10001 | System is busy, please retry later |
| 10002 | Request timeout. |
| 11000 | No permission |
| 11200 | You have sent too many sms codes today. |
| 11201 | Request SMS verify code too frequently |
| 11202 | The sms verify code is locked due to too many failure attempt. |
| 11203 | Wrong sms verify code. |
| 12000 | Type of GET request is not supported. |
| 12001 | Invalid params. |
| 12002 | nvalid request id. |
| 12003 | Invalid sender id. |
| 12004 | Invalid signature. |
| 12005 | FileName too long. |
| 12006 | File too big. |
| 12007 | ile can not match type. |
| 12008 | Please input country code. |
| 12009 | Please input mobile |
| 12010 | Invalid mobile number. |
| 12011 | Please input sms code |
| 12012 | Please input a valid amount. |
| 12013 | Please upload your file |
| 12014 | Please enter the nation |
| 12015 | Invalid birthday. |
| 12016 | Invalid mati request id. |
| 12017 | Please select a valid channel id. |
| 12018 | Please select a valid currency. |
| 12019 | Please input a valid account type. |
| 12020 | Please input a valid txType. |
| 12021 | Please input a valid txStatus. |
| 12022 | Unknown channel or sender |
| 12023 | Duplicate request. |
| 12024 | Invalid timestamp. |
| 13000 | Account does not exist. |
| 13001 | The user account has been locked. |
| 13002 | The user account has been closed. |
| 13003 | Account is abnormal. |
| 13004 | Account already exists. |
| 13005 | User is not found. |
| 13200 | Customer's kyc has not been passed. |
| 13105 | No such agreement |
| 13201 | Customer has passed the onboarding process. |
| 13202 | User's KYC information cannot be found. |
| 13203 | ID number has been registered. |
| 13204 | Onboarding request is under review. |
| 13205 | Customer is under 18. |
| 13206 | Onboarding media is not found. |
| 13207 | Onboarding status is not found. |
| 13208 | Onboarding request is not found. |
| 13209 | Please create your account |
| 13210 | You have opened an account. |
| 13211 | The onboarding request can not be modified as it is under reviewing or it has already been finalised (pass, rejected or timeout). |
| 13212 | Failed to create wallet customer. |
| 13213 | Failed to create wallet account. |
| 13214 | invalid monthly income. |
| 13215 | invalid employment status. |
| 13216 | this onboarding request has been audited. |
| 13217 | please upload the back side photo |
| 13218 | please upload jpg/jpeg/png type image |
| 13219 | image sizes must under 10MB |
| 13220 | please input at least one of this [userId,onboardingRequestId mobile] param |
| 13221 | please input a valid certificate type |
| 13222 | mobile has been register |
| 13223 | invalid reject reasons |
| 13224 | please input at least one of this [userId,mobile] param |
| 13225 | invalid status for audit,only status [2,9] for audit. |
| 13226 | Please input a valid kraPin. |
| 13227 | tier 2 onboarding request is not passed. |
| 13228 | you have upgraded your account to tier 1. |
| 13229 | your upgrade request is processing. |
| 13300 | Please withdraw all of the money before you close account. |
| 13301 | Failed to close account. Please contact support. |
| 13302 | short code exist for this user. |
| 13303 | account not found by this short code |
| 13304 | onboard info not found or not passed, please submit onboard request first |
| 13305 | onboard detail not match |
| 13306 | application not found or have been confirmed |
| 13307 | application not found |
| 13308 | account application reached maximum limit |
| 13309 | mobile change application reached maximum limit |
| 14001 | Transaction does not exist. |
| 14002 | Transaction Type does not exist. |
| 14003 | The pay-in channel is not supported. |
| 14004 | Account name does not match |
| 14005 | The accounts have different currencies. |
| 14006 | Too many transfers today. |
| 14007 | Too much transfer amount today. |
| 14008 | Cannot transfer to the same account. |
| 14009 | Insufficient account balance |
| 14010 | Cannot close account, because balance is not 0. |
| 14011 | product does not exist. |
| 14012 | bank code does not exist. |
| 14013 | business account does not exist. |
| 14014 | invalid payee accounts. |
| 14015 | amount of withdraw to M-PESA must greater than 10 KES per transaction. |
| 14016 | batch size is limited to be no more %s transactions per call. |
| 14017 | batch id not exist. |
| 14018 | batch transfer error. |
| 14019 | failed transaction missing error code. |
| 14020 | the transactions are not fully match this batch. |
| 14021 | TRANSACTION_LIMITATION |
| 14022 | inter bank transaction limit exceed |
| 14023 | amount of inter bank transfer must greater than 10 KES |
| 14024 | nvalid payee type or payee type not match. |
| 14025 | transaction limit exceed |
| 14026 | invalid bill order |
| 14027 | payment rejected |
| 14028 | internal error |
| 14029 | transaction have been processed |
| 14030 | payment not found. |
| 14031 | transaction have been confirmed. |
| 14032 | amount of deposit from M-PESA must not greater than 150000 KES per transaction. |
| 14033 | Insufficient amount for deposit from M-PESA |
| 14034 | bulk payment size over range |
| 14035 | bulk payment not exist |
| 14036 | bulk payment had been confirmed |
| 14037 | invalid otp mobile. |
| 14038 | currency mismatch |
| 14039 | unsupported bank code in foreign currency transaction |
| 14040 | foreign currency exchange must between the same user's accounts |
| 14041 | M-PESA outbound amount limit exceed |
| 14042 | white list check error |
| 14043 | account not in white list |
| 15001 | query time over range. |
| 15002 | query page oversize. |
| 15003 | job not exist. |
| 15004 | invalid query range |
| 15005 | the query is cooling down, please wait |
| 18000 | Failed to upload file. |
| 18001 | Failed to process file. |