#Error reference
All errors extend NagadError and carry a stable code.
#SDK errors
| Class | Cause | What to do |
|---|---|---|
NagadApiError (and subclasses below) |
Nagad answered with an error. rawCode, httpStatus and rawResponse are available. |
Look up the code below. |
NagadCryptoCapabilityError |
A custom crypto provider cannot do RSA PKCS#1 v1.5 decryption. | You configured your own provider that cannot decrypt. Use the default provider (it falls back automatically), see Runtime compatibility. |
NagadCryptoError |
Signing, encryption or key parsing failed. | Check the keys. |
NagadSignatureVerificationError |
Nagad's response signature did not verify. | Check pgPublicKey and signatureAlgorithm. Treat the response as untrusted. |
NagadVerificationMismatchError |
Amount, order id or merchant differ from what you expected. | Do not fulfil. Investigate. |
NagadTimeoutError |
The call timed out. | The outcome is unknown. Re-verify with reconcile(); do not ask the customer to pay again. |
NagadSessionNotFoundError |
No stored session for the reference. | The callback is unexpected or the store lost data. |
NagadReplayAttackError |
A finished payment's callback was replayed. | Ignore; already processed. |
NagadConcurrentVerificationError |
Another worker is verifying this payment. | Retry shortly. |
NagadDuplicateOrderIdError |
The order id was already used. | Use a new order id. |
#Nagad codes mapped by the SDK
Nagad publishes its full code list to merchants during onboarding. These are the codes mapNagadApiError turns into specific classes; any other code becomes a plain NagadApiError with Nagad's message. This table is checked against the code by a test.
| Nagad code | SDK error class | Meaning | What to do |
|---|---|---|---|
16_0006_004 | NagadInvalidMerchantError | The merchant ID is not recognised. | Check merchantId and that the keys belong to the same environment as baseUrl. |
16_0006_050 | NagadInvalidMerchantError | The merchant ID is not recognised. | Check merchantId and the environment. |
16_0006_052 | NagadInvalidMerchantError | The merchant ID is not recognised. | Check merchantId and the environment. |
16_0006_053 | NagadInactiveMerchantError | The merchant account is inactive. | Contact your Nagad account manager. |
16_0006_061 | NagadKeyError | Invalid merchant key (the gateway could not use your public key). | Upload the matching public key in the merchant portal; check the private key you configured. |
16_0006_064 | NagadMissingHeaderError | A mandatory request header is missing. | Set serverIp (the X-KM-IP-V4 header) and check any proxy that strips headers. |
16_0006_068 | NagadInvalidOrderIdError | Invalid order id: must be 5-20 alphanumeric characters. | Use generateOrderId() or an order id that matches the rule. |
16_0006_076 | NagadClockSkewError | The transaction time is outside the allowed window. | Fix the server clock (NTP). The SDK sends Bangladesh time (UTC+6). |
16_0006_080 | NagadInvalidCurrencyError | Invalid currency: only 050 (BDT) is accepted. | Do not override currency. |
16_0006_081 | NagadInvalidTimestampError | Invalid date-time format. | Check any custom clock passed to the client. |
16_0006_083 | NagadDuplicateOrderIdError | Duplicate order id on the same day. | Use a new order id for every attempt. |