error_code, error_source, error_step and description. Branch your handling on error_reason, which is the stable field across both the registration and debit flows.
error_code is a broad class, so many reasons share one code. Use error_reason to decide what to do, and error_code only to decide how loudly to log.Bad Request Errors
Given below is the list of bad request errors.beneficiary_account_not_found
beneficiary_account_not_found
- Description: Payment failed as the beneficiary account was not found. Please use another account.
- Source:
business - Step:
payment_response
mandate_already_executed
mandate_already_executed
- Description: This payment has already been processed for the current cycle. No further executions are permitted.
- Source:
business - Step:
payment_debit_response
mandate_expired
mandate_expired
- Description: This UPI Autopay has expired. Please set it up again.
- Source:
business - Step:
payment_initiation
record_not_found
record_not_found
- Description: Your session ended. This may happen if you didn’t complete the request or took too long. Please try again.
- Source:
internal - Step:
payment_request
request_validation_failed
request_validation_failed
Gateway Errors
Given below is the list of gateway errors.account_changed
account_changed
- Description: Your account information has changed. Please set up the mandate again with your current account.
- Source:
customer - Step:
payment_response
account_restricted
account_restricted
- Description: Payment failed due to a technical issue. Please contact support.
- Source:
remitter_bank - Step:
payment_credit_response
account_state_blocked
account_state_blocked
- Description: Your account is blocked or frozen. Please contact your bank to resolve this.
- Source:
remitter_bank - Step:
payment_debit_request
account_state_forbidden
account_state_forbidden
- Description: Payment is not allowed for this account. Please contact your bank or try a different account.
- Source:
remitter_bank - Step:
payment_authorization
account_type_invalid
account_type_invalid
- Description: Payment is not allowed for this account type. Please try a different account or contact your bank.
- Source:
remitter_bank - Step:
payment_response
account_type_not_supported
account_type_not_supported
- Description: Payment is not allowed for this account type. Please try a different account or contact your bank.
- Source:
remitter_bank - Step:
payment_authentication
address_dispatch_failed
address_dispatch_failed
- Description: Payment couldn’t be completed due to a temporary issue. Any debited amount will be refunded in 4-5 business days.
- Source:
upi_service - Step:
payment_debit_response
address_resolution_failed
address_resolution_failed
- Description: We couldn’t verify your UPI ID. Please check it’s correct and try again.
- Source:
customer - Step:
payment_status_request
amount_invalid_gateway_error
amount_invalid_gateway_error
- Description: Payment failed due to a technical issue. Please try again or contact support if this continues.
- Source:
remitter_bank - Step:
payment_response
bank_not_supported_for_mandate
bank_not_supported_for_mandate
- Description: Your bank doesn’t support UPI Autopay. Please use a different bank account.
- Source:
remitter_bank - Step:
payment_response
bank_technical_error
bank_technical_error
business_blocked_by_customer
business_blocked_by_customer
- Description: Payment failed as you have blocked requests from this business. Please unblock this business in your UPI app and try again.
- Source:
customer - Step:
payment_authentication
card_lost_or_stolen
card_lost_or_stolen
- Description: This account cannot be used due to security reasons. Please contact your bank or use a different account.
- Source:
remitter_bank - Step:
payment_initiation
card_not_found
card_not_found
- Description: Card record not found. Please contact your bank.
- Source:
remitter_bank - Step:
payment_response
collect_notification_failed
collect_notification_failed
- Description: Payment failed as the collect notification expired. Please try again.
- Source:
upi_service - Step:
payment_response
compliance_violation
compliance_violation
- Description: This payment was declined by the bank due to compliance restrictions. Please contact your bank for details.
- Source:
remitter_bank - Step:
payment_debit_response
customer_account_invalid
customer_account_invalid
- Description: Your account details have changed. Please update your UPI profile or contact your bank.
- Source:
remitter_bank - Step:
payment_debit_response
customer_account_not_found
customer_account_not_found
- Description: This account could not be found. Please contact your bank or try again.
- Source:
remitter_bank - Step:
payment_debit_request
customer_account_status_inactive
customer_account_status_inactive
- Description: Your account is inactive or dormant. Please contact your bank to activate it.
- Source:
remitter_bank - Step:
payment_debit_request
customer_invalid_mobile_number
customer_invalid_mobile_number
- Description: Your registered mobile number has been updated. Please update your UPI profile or contact your bank.
- Source:
remitter_bank - Step:
payment_request
customer_mpin_not_set
customer_mpin_not_set
- Description: UPI PIN is not set for this account. Please set up your UPI PIN and try again.
- Source:
customer - Step:
payment_debit_response
customer_psp_fingerprint_mismatch
customer_psp_fingerprint_mismatch
- Description: Payment failed due to a security check. Please try again from the same device.
- Source:
customer - Step:
payment_response
customer_psp_timeout
customer_psp_timeout
- Description: Your UPI app took too long to respond. Please try again.
- Source:
customer_psp - Step:
payment_debit_response
customer_vpa_not_supported
customer_vpa_not_supported
- Description: Autopay cannot be set up on this UPI ID. Please use a different UPI ID or account.
- Source:
customer_psp - Step:
payment_debit_request
debit_exceeds_blocked_amount
debit_exceeds_blocked_amount
- Description: Payment amount exceeds blocked amount. Please contact support.
- Source:
remitter_bank - Step:
payment_authentication
declined_by_customer_psp
declined_by_customer_psp
- Description: Payment was declined by your UPI app. Please try again or use a different method.
- Source:
customer_psp - Step:
payment_authentication
declined_by_remitter_bank
declined_by_remitter_bank
device_not_permitted
device_not_permitted
- Description: This device is restricted for the payment. Please use a registered device or contact your bank.
- Source:
upi_service - Step:
payment_response
duplicate_request
duplicate_request
first_time_user_freeze_period
first_time_user_freeze_period
- Description: You’ve exceeded the ₹5,000 limit for new UPI users in the first 24 hours. Please wait or set up a mandate for a lower amount.
- Source:
customer - Step:
payment_debit_request
first_transaction_limit_exceeded
first_transaction_limit_exceeded
- Description: Payment declined as your first transaction is limited to ₹5,000. Please retry later.
- Source:
customer - Step:
payment_response
funds_blocked_for_mandate
funds_blocked_for_mandate
- Description: Insufficient balance in your account. Please add funds and try again.
- Source:
customer - Step:
payment_response
incorrect_pin_entered
incorrect_pin_entered
insufficient_funds
insufficient_funds
- Description: Insufficient balance in your account. Please add funds and try again.
- Source:
customer - Step:
payment_debit_request
invalid_transaction_id
invalid_transaction_id
- Description: Payment failed due to a technical issue. Please try again or contact support if this continues.
- Source:
upi_service - Step:
payment_response
invalid_vpa
invalid_vpa
mandate_cancelled_by_user
mandate_cancelled_by_user
- Description: You cancelled the payment. Set it up again to complete your order.
- Source:
customer - Step:
payment_response
mandate_collect_request_expired
mandate_collect_request_expired
- Description: You didn’t approve the request in your UPI app. Please try again and approve within 10 minutes.
- Source:
customer - Step:
payment_authentication
mandate_creation_expired
mandate_creation_expired
- Description: The mandate setup has timed out. Please try again and approve the request in your UPI app within 10 minutes.
- Source:
customer - Step:
payment_authentication
mandate_creation_limit_exceeded
mandate_creation_limit_exceeded
- Description: You’ve reached the maximum number of UPI Autopay mandates allowed by your bank. Please use a different account.
- Source:
remitter_bank - Step:
payment_response
mandate_limit_exceeded_remitter_decline
mandate_limit_exceeded_remitter_decline
- Description: Payment failed as your bank’s limit has been exceeded. Please contact your bank or try a different account.
- Source:
remitter_bank - Step:
payment_response
mandate_not_actioned_by_user
mandate_not_actioned_by_user
- Description: Payment setup timed out. Please try again.
- Source:
customer - Step:
payment_response
mandate_paused
mandate_paused
- Description: This UPI Autopay is paused. Please unpause it to continue payments with the business.
- Source:
customer - Step:
payment_response
mandate_revoked
mandate_revoked
- Description: This UPI Autopay was cancelled. Please set it up again.
- Source:
customer - Step:
payment_response
merchant_psp_error
merchant_psp_error
- Description: Payment failed due to a technical issue. Please try again.
- Source:
payee_psp - Step:
payment_debit_response
payee_psp_system_error
payee_psp_system_error
- Description: Payment failed due to a technical issue. Please try again or contact support if this continues.
- Source:
payee_psp - Step:
payment_initiation
payee_psp_timeout
payee_psp_timeout
- Description: Payment failed due to a technical issue. Please try again or contact support if this continues.
- Source:
payee_psp - Step:
payment_debit_request
pin_credential_block_missing
pin_credential_block_missing
- Description: Your UPI app did not send the UPI PIN needed to authorise this mandate. Please try again and approve with your UPI PIN.
- Source:
remitter_bank - Step:
payment_initiation
psp_amount_cap_exceeded
psp_amount_cap_exceeded
- Description: This amount cannot be set up for UPI Autopay. Please retry with another UPI app or payment method.
- Source:
customer_psp - Step:
payment_status_request
psp_frequency_limit_exceeded
psp_frequency_limit_exceeded
- Description: You’ve exceeded the number of allowed transactions. Please try again later or contact your bank.
- Source:
customer_psp - Step:
payment_authorization
remitter_bank_throttling
remitter_bank_throttling
- Description: Your bank is experiencing high traffic. Please try again in a few moments.
- Source:
remitter_bank - Step:
payment_response
remitter_bank_timeout
remitter_bank_timeout
request_not_found
request_not_found
- Description: Payment failed due to a technical issue. Please try again.
- Source:
remitter_bank - Step:
payment_response
request_timeout
request_timeout
request_validation_failed
request_validation_failed
risk_declined_by_remitter_bank
risk_declined_by_remitter_bank
sequence_mismatch
sequence_mismatch
signature_corrupt
signature_corrupt
- Description: Payment was declined for security reasons. Please contact your bank for assistance.
- Source:
remitter_bank - Step:
payment_response
timeout_at_remitter_bank
timeout_at_remitter_bank
transaction_amount_limit_exceeded
transaction_amount_limit_exceeded
transaction_frequency_limit_exceeded
transaction_frequency_limit_exceeded
- Description: You’ve exceeded the number of allowed transactions on this account. Please try again later or contact your bank.
- Source:
remitter_bank - Step:
payment_response
validation_failed_at_remitter
validation_failed_at_remitter
vpa_restricted
vpa_restricted
- Description: You have restricted this UPI ID. Please unblock it in your UPI app settings and try again.
- Source:
customer - Step:
payment_response
Server Errors
Given below is the list of server errors.internal_server_error
internal_server_error
- Description: Payment was unsuccessful due to a temporary issue on our side. Any amount deducted will be refunded within 5-7 working days.
- Source:
internal - Step:
payment_request