Error codes
The following are the common error codes returned by the Subscription APIs:| Error Code | Description | Resolution |
|---|---|---|
subscription_id_missing | Subscription ID is required but missing in the request | Ensure the subscription ID is included in your API request |
plan_id_missing | Plan ID is missing, invalid, or not found | Verify the plan ID exists and is correctly specified |
payment_id_missing | Payment ID is missing or not found | Include a valid payment ID in your request |
subscription_id_missing_request_failed_failed | Subscription ID missing; request failed | Add the required subscription ID parameter |
invalid_payment_type | Invalid payment type specified | Use supported payment types: ‘E_MANDATE’, ‘UPI’, or ‘CARD’ |
subscription_does_not_exist | Subscription doesn’t exist for the provided reference ID | Verify the subscription reference ID is correct |
authorization_payment_info_mismatch | Authorization payment info doesn’t match subscription creation info | Ensure payment details match between subscription creation and authorization |
tpv_not_supported | TPV currently not allowed for Intent and QR auth flow | Use alternative auth flows when TPV is enabled |
Transaction failure reasons
The following are the detailed failure reasons categorised by their nature:- Account issues
- Balance and limit issues
- Mandate issues
- Fraud and security
- Technical issues
- Customer action required
- Invalid data and validation
- Know your customer and documentation
- System and processing status
- Notification issues
Account issues
The following are the account-related error codes:| Error | Description | Resolution |
|---|---|---|
ACCOUNT CLOSED | The account has been closed and all associated mandates were deactivated | Create a new mandate with a different account for the customer |
Account Blocked or frozen | Account is temporarily blocked (for example, KYC not updated) | Customer needs to contact their bank to unblock the account |
DEBIT HAS BEEN FAILED | ACCOUNT DOES NOT EXIST (REMITTER) | Account verification failed due to incorrect account details | Verify and update correct account information |
Not a CBS act no.or old act no.representwithCBS no | Account given for debit is old/non CBS/wrong/invalid | Use a valid CBS-enabled account number |
DEBIT HAS BEEN FAILED | REMITTER CBS OFFLINE | Core Banking System is offline | Wait for CBS to come online and retry |
U30|DEBIT HAS BEEN FAILED|YE|REMITTING ACCOUNT BLOCKED/FROZEN | Remitting account is blocked or frozen | Customer should contact their bank to resolve account issues |
Balance and limit issues
The following are the balance and limit-related error codes:| Error | Description | Resolution |
|---|---|---|
Balance Insufficient | Insufficient funds in customer account | Customer should add funds or retry when balance is available |
DEBIT HAS BEEN FAILED | INSUFFICIENT FUNDS IN CUSTOMER (REMITTER) ACCOUNT | Insufficient balance in customer account | Recommend customer to maintain sufficient balance before retry |
U30|DEBIT HAS BEEN FAILED|Z9|INSUFFICIENT FUNDS IN CUSTOMER (REMITTER) ACCOUNT | Insufficient funds in remitter account | Customer needs to ensure adequate balance |
Amount Exceeds E-mandate Limit | Transaction amount exceeds the e-mandate limit | Reduce amount or increase mandate limit if supported |
DEBIT HAS BEEN FAILED | PER TRANSACTION LIMIT EXCEEDED AS SET BY REMITTING MEMBER | Per transaction limit exceeded | Use amount within the set transaction limits |
U29|ADDRESS RESOLUTION IS FAILED|QL|MANDATE DEBIT IS BEYOND PSP SPECIFIED AMOUNT CAP | Amount limit is breached | Ensure amount is within PSP specified limits |
DEBIT HAS BEEN FAILED | MANDATE REQUEST LIMIT HAS BREACHED | Mandate request limit has been breached | Wait for limit reset or contact support |
U30|DEBIT HAS BEEN FAILED|QK|MANDATE REQUEST LIMIT HAS BREACHED | Mandate request limit exceeded | Review and adjust mandate limits |
Not Arranged For | Bank account isn’t set up to facilitate debit transaction | Customer should contact bank to set up debit facility |
Mandate issues
The following are the mandate-related error codes:| Error | Description | Resolution |
|---|---|---|
Invalid UMRN or Inactive Mandate | Mandate has been deactivated by NPCI or cancelled by customer/merchant | Create a new mandate for the customer |
Mandate Cancelled | Mandate has been cancelled by customer or merchant | Create a new mandate to continue debits |
Record Level Error: Invalid Mandate Info | Mandate cancelled by customer from bank | Create a new mandate with updated information |
DEBIT HAS BEEN FAILED | MANDATE HAS BEEN REVOKED | Mandate has been revoked | Create a new mandate for the customer |
DEBIT HAS BEEN FAILED | MANDATE SIGNATURE IS TAMPERED OR CORRUPT (REMITTER) | Mandate signature is corrupted | Customer should contact issuing bank |
DUPLICATE MANDATE REQUEST FOR SAME ITEM | Duplicate mandate request submitted | Avoid duplicate requests or check existing mandates |
Mandate Qr tampered | Mandate QR code has been tampered with | Generate a new mandate with fresh QR code |
U29|ADDRESS RESOLUTION IS FAILED|QB|MANDATE IS ALREADY HONOURED | Duplicate transaction attempt | Ensure transaction isn’t a duplicate of a previously successful one |
Invalid frequency | Invalid frequency specified for LOAN category | Use appropriate frequency as per NPCI guidelines |
Fraud and security
The following are the fraud and security-related error codes:| Error | Description | Resolution |
|---|---|---|
DEBIT HAS BEEN FAILED | SUSPECTED FRAUD | Transaction flagged as suspected fraud | Customer should contact their bank for clearance |
U30|DEBIT HAS BEEN FAILED|K1|SUSPECTED FRAUD, DECLINE / TRANSACTIONS DECLINED BASED ON RISK SCORE BY REMITTER | Risk-based decline by remitter bank | Customer may retry or contact bank |
ADDRESS RESOLUTION IS FAILED | TRANSACTION CANNOT BE COMPLETED. COMPLIANCE VIOLATION (REMITTER) | Compliance violation detected | Ensure transaction complies with regulatory requirements |
DEBIT HAS BEEN FAILED | DO NOT HONOUR (REMITTER) | Debit transaction rejected by issuing bank | Customer should contact their bank |
Technical issues
The following are the technical error codes:| Error | Description | Resolution |
|---|---|---|
REMITTER BANK NOT AVAILABLE | Remitter bank system is unavailable | Retry the transaction after some time |
DEBIT TIMEOUT | REMITTER/ISSUER UNAVAILABLE (TIMEOUT) | Bank system timeout occurred | Retry the transaction when bank systems are stable |
U67|DEBIT TIMEOUT|UT|REMITTER/ISSUER UNAVAILABLE (TIMEOUT) | Timeout from remitter or issuer | Retry during stable network conditions |
REMITTER BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE | Bank system experiencing high traffic or technical issues | Retry during off-peak hours |
U90|REMITTER BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE | High response time from remitter bank | Retry when bank systems are more responsive |
U91|BENEFICIARY BANK DEEMED HIGH RESPONSE TIME CHECK DECLINE | Beneficiary bank system issues | Retry when bank systems are stable |
No response received from bank within the prescribed API time limit | Bank API timeout | Retry the transaction |
ADD_RESLN_DISPATCH_FAILED | Address resolution dispatch failure | Contact support for technical assistance |
Customer action required
The following are the error codes that require customer action:| Error | Description | Resolution |
|---|---|---|
No action performed by customer | Customer didn’t complete the authorization process | Customer needs to complete the payment flow |
COLLECT EXPIRED | Customer didn’t complete auth after entering VPA | Customer should complete the transaction within time limit |
RESPMANDATE TIMEOUT AT REMITTER END | Customer didn’t honor the mandate within time | Customer should respond to mandate requests |
RESPMANDATE DECLINED BY REMITTER BANK | Remitter bank declined the mandate | Customer should contact their bank |
RESPAUTHMANDATE EXPIRED | No action performed on collect request and it expired | Customer should complete authorization within time limit |
RESPAUTHMANDATE DECLINED BY PSP | PSP declined the authorization mandate | Contact support for assistance |
Transaction Open Status | Customer closed transaction page before completion or retried failed transaction | Complete the transaction without closing the page |
No Details available for Requested MandateReqID | Customer cancelled mandate before reaching NPCI page | Reinitiate the mandate creation process |
Invalid data and validation
The following are the data validation error codes:| Error | Description | Resolution |
|---|---|---|
U29|ADDRESS RESOLUTION IS FAILED|ZH|INVALID VIRTUAL ADDRESS | Invalid VPA used in transaction | Use a valid and verified VPA |
ADDRESS RESOLUTION IS FAILED | INVALID VIRTUAL ADDRESS | Invalid Virtual Address during VPA validation | Verify and use correct VPA |
DEBIT HAS BEEN FAILED | INVALID TRANSACTION OR IF MEMBER IS NOT ABLE TO FIND ANY APPROPRIATE RESPONSE CODE (REMITTER) | Invalid transaction or unrecognized response | Retry with valid transaction details |
U30|DEBIT HAS BEEN FAILED|XB|INVALID TRANSACTION OR IF MEMBER IS NOT ABLE TO FIND ANY APPROPRIATE RESPONSE CODE (REMITTER) | Invalid transaction from remitter | Verify transaction details and retry |
DEBIT HAS BEEN FAILED | INVALID RESPONSE CODE | Invalid response received from bank | Retry the transaction |
U30|DEBIT HAS BEEN FAILED|XD|INVALID AMOUNT (REMITTER) | Invalid amount specified | Use valid amount format and value |
DEBIT HAS BEEN FAILED | RegIdDetails must be present | Required registration details missing | Ensure all required details are provided |
U30|DEBIT HAS BEEN FAILED|V1|RegIdDetails must be present | Registration details missing | Include all required registration information |
DEBIT HAS BEEN FAILED | Id name must be present | Required ID name field missing | Include the ID name field in the request |
Know your customer and documentation
The following are the KYC and documentation-related error codes:| Error | Description | Resolution |
|---|---|---|
Aadhaar number does not have mobile number registered with uidai | Mobile number not linked with Aadhaar | Customer should link mobile number with Aadhaar |
Payer Account Validation Failure | TPV verification failed | Ensure correct account details for TPV verification |
System and processing status
The following are the system and processing status error codes:| Error | Description | Resolution |
|---|---|---|
Internal Payment Failed | Internal system error during payment processing | Retry the transaction or contact support |
Charge couldn't happen on time | Previous charge was in progress, preventing next charge | Wait for previous charge to complete |
Previous request in progress | Previous request for same action is still being processed | Wait for previous request to complete before retrying |
debit has been failed | Bank didn’t send any failure reason | Check with bank for specific failure details |
Notification issues
The following are the notification-related error codes:| Error | Description | Resolution |
|---|---|---|
Notification couldn't be sent to the customer | Pre-debit notification failed to send | Ensure customer contact details are correct |
DEBIT HAS BEEN FAILED | Unable to Notify the Customer | Pre-debit notification delivery failed | Update customer contact information |
Error response structure
Subscription API errors follow this structure:Best practices for error handling
The following are the recommended practices for handling subscription errors: Implement retry logic:- For timeout and temporary errors, implement exponential backoff retry logic.
- Start with a 1-second delay, double the delay for each subsequent retry.
- Use a maximum of 3-5 retry attempts.
- Apply different retry strategies for different error types.
- Provide clear, actionable error messages to customers.
- Include specific steps they need to take for resolution.
- Avoid technical jargon in customer-facing messages.
- Monitor mandate status.
- Proactively create new mandates when existing ones are cancelled or expired.
- Implement mandate renewal work flows before expiration.
- Advise customers to maintain sufficient balance before scheduled debits.
- Send pre-debit notifications to remind customers.
- Implement balance check APIs where available.
- Log all errors with timestamps and request details.
- Set up alerts for critical error patterns.
- Analyse error trends to identify systemic issues.
- Provide alternative payment methods when subscription payment fails.
- Implement fallback mechanisms for critical payment flows.
- Maintain service availability despite individual payment failures.
- Handle fraud-related errors with additional verification steps.
- Implement risk scoring for suspicious transaction patterns.
- Maintain compliance with regulatory requirements.
For additional API error codes and web hook error structures, refer to the Payment Errors documentation.