Error Codes and Reasons

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:

{
  "status": "ERROR",
  "subCode": "400",
  "message": "Error description",
  "reason": "Detailed error reason"
}

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.

Customer communication:

Provide clear, actionable error messages to customers.
Include specific steps they need to take for resolution.
Avoid technical jargon in customer-facing messages.

Mandate management:

Monitor mandate status.
Proactively create new mandates when existing ones are cancelled or expired.
Implement mandate renewal work flows before expiration.

Balance monitoring:

Advise customers to maintain sufficient balance before scheduled debits.
Send pre-debit notifications to remind customers.
Implement balance check APIs where available.

Error logging and monitoring:

Log all errors with timestamps and request details.
Set up alerts for critical error patterns.
Analyse error trends to identify systemic issues.

Graceful degradation:

Provide alternative payment methods when subscription payment fails.
Implement fallback mechanisms for critical payment flows.
Maintain service availability despite individual payment failures.

Security considerations:

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.

Payments API

v2026-01-01

Other Versions

Error Codes and Reasons

Error codes

Transaction failure reasons

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

Error response structure

Best practices for error handling

​Error codes

​Transaction failure reasons

​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

​Error response structure

​Best practices for error handling

Error codes

Transaction failure reasons

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

Error response structure

Best practices for error handling