#Error reference
#SDK error classes
All errors extend BkashError and have a stable code.
| Class | Code | Cause | What to do |
|---|---|---|---|
BkashApiError |
BKASH_API_<externalCode> |
bKash answered with an error code. externalCode, httpStatus and raw are available. |
Look the code up below. Show the message to the customer, not the code. |
BkashRateLimitError |
BKASH_RATE_LIMIT |
The Grant/Refresh Token limit was hit (HTTP 429). | Wait for retryAfterMs. Check that every process shares one token store. |
BkashVerificationMismatchError |
BKASH_VERIFICATION_MISMATCH |
bKash's result differs from the amount, currency or invoice you expected. | Do not fulfil. Investigate; this can indicate tampering or a bug. |
BkashTimeoutError |
BKASH_TIMEOUT |
Execute timed out and Query Payment could not confirm the outcome. | Outcome is unknown. Show "pending, do not pay again" and re-query later. |
BkashDuplicateExecutionError |
BKASH_DUPLICATE_EXECUTION |
Another execute is in progress, or error 2062 without a Completed payment. |
Wait and query the payment. |
BkashWebhookVerificationError |
BKASH_WEBHOOK_VERIFICATION |
An IPN message failed verification. | Reject it. Do not act on its content. |
BkashFeatureNotSupportedError |
BKASH_FEATURE_NOT_SUPPORTED |
The feature is not implemented, or not available for the configured apiVersion. |
See feature status. |
#HTTP handler responses
| Situation | Status | Body |
|---|---|---|
| Outcome unknown (timeout) | 202 |
{ success:false, status:"unknown", error } |
| Mismatch / duplicate | 409 |
{ success:false, status:"mismatch" | "duplicate" } |
| Rate limited | 429 |
{ success:false } |
| bKash error | 400 |
{ success:false, code, error } |
| Customer cancelled or failed | 400 |
{ success:false, status } |
| Webhook failed verification | 401 |
{ success:false } |
| Unexpected error | 500 |
{ success:false, error:"bKash request failed." } (no internals) |
#bKash error codes
These are copied from the published bKash error tables (payment and refund). Meanings are bKash's wording. The mapping in KNOWN_BKASH_ERRORS is checked against this table by a test.
| Code | Meaning (bKash) |
|---|---|
503 | System is undergoing maintenance. Please try again later |
2001 | Invalid App Key |
2002 | Invalid Payment ID |
2003 | Process failed |
2004 | Invalid firstPaymentDate |
2005 | Invalid frequency |
2006 | Invalid amount |
2007 | Invalid currency |
2008 | Invalid intent |
2009 | Invalid Wallet |
2010 | Invalid OTP |
2011 | Invalid PIN |
2012 | Invalid Receiver MSISDN |
2013 | Resend Limit Exceeded |
2014 | Wrong PIN |
2015 | Wrong PIN count exceeded |
2016 | Wrong verification code |
2017 | Wrong verification limit exceeded |
2018 | OTP verification time expired |
2019 | PIN verification time expired |
2020 | Exception Occurred |
2021 | Invalid Mandate ID |
2022 | The mandate does not exist |
2023 | Insufficient Balance |
2024 | Exception occurred |
2025 | Invalid request body |
2026 | The reversal amount cannot be greater than the original transaction amount |
2027 | The mandate corresponding to the payer reference number already exists and cannot be created again |
2028 | Reverse failed because the transaction serial number does not exist |
2029 | Duplicate for all transactions |
2030 | Invalid mandate request type |
2031 | Invalid merchant invoice number |
2032 | Invalid transfer type |
2033 | Transaction not found |
2034 | The transaction cannot be reversed because the original transaction has been reversed |
2035 | Reverse failed because the initiator has no permission to reverse the transaction |
2036 | The direct debit mandate is not in Active state |
2037 | The account of the debit party is in a state which prohibits execution of this transaction |
2038 | Debit party identity tag prohibits execution of this transaction |
2039 | The account of the credit party is in a state which prohibits execution of this transaction |
2040 | Credit party identity tag prohibits execution of this transaction |
2041 | Credit party identity is in a state which does not support the current service |
2042 | Reverse failed because the initiator has no permission to reverse the transaction. |
2043 | The security credential of the subscriber is incorrect. |
2044 | Identity has not subscribed to a product that contains the expected service or the identity is not in Active status. |
2045 | The MSISDN of the customer does not exist. |
2046 | Identity has not subscribed to a product that contains requested service. |
2047 | TLV Data Format Error |
2048 | Invalid Payer Reference |
2049 | Invalid Merchant Callback URL |
2050 | Agreement already exists between payer and merchant |
2051 | Invalid Agreement ID |
2052 | Agreement is in incomplete state |
2053 | Agreement has already been cancelled |
2054 | Agreement execution pre-requisite hasn't been met |
2055 | Invalid Agreement State |
2056 | Invalid Payment State |
2057 | Not a bKash Account |
2058 | Not a Customer Wallet |
2059 | Multiple OTP request for a single session denied |
2060 | Payment execution pre-requisite hasn't been met |
2061 | This action can only be performed by the agreement or payment initiator party |
2062 | The payment has already been completed |
2063 | Mode is not valid as per request data |
2064 | This product mode currently unavailable |
2065 | Mendatory field missing |
2066 | Agreement is not shared with other merchant |
2067 | Invalid permission |
2068 | Transaction has already been completed |
2069 | Transaction has already been cancelled |
2071 | Refund after %s days not allowed |
2072 | Refund amount not valid |
2073 | Invalid SKU |
2074 | The transaction cannot be reversed |
2075 | SKU Character Limit Exceeded |
2076 | Reason Character Limit Exceeded |
2077 | Invalid TrxID |
2078 | Invalid Reason |
2079 | Invalid app Token |
2080 | The identity is not permitted to initiate this transaction |
2081 | The identity of the debit or credit party is in a state which prohibits the execution of this transaction |
2082 | The merchant is not permitted to initiate this transaction |
2116 | The agreement execution has already been completed |
2117 | The payment execution has already been completed |
2118 | The Platform value is invalid |
2119 | The authorized payment has already been processed |
2127 | Transaction not yet completed |
Not every code is in a table (for example 9999 for invalid credentials appears in responses). Unknown codes keep bKash's own message.