> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 5. Error Codes

> Error codes, sources, steps and descriptions for UPI Autopay mandate registrations and auto-debits.

Available in
🇮🇳 India

Every failure reason UPI Autopay returns, for mandate registrations and for auto-debits, with the error code, source, step and customer-facing description.

Open a reason below to see its `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.

> [!NOTE]
>
> **Match on reason, not on the code**
>
> `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.

> [accordion] beneficiary\_account\_not\_found
>
> * **Description**: Payment failed as the beneficiary account was not found. Please use another account.
> * **Source**: `business`
> * **Step**: `payment_response`

> [accordion] 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`

> [accordion] mandate\_expired
>
> * **Description**: This UPI Autopay has expired. Please set it up again.
> * **Source**: `business`
> * **Step**: `payment_initiation`

> [accordion] 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`

> [accordion] request\_validation\_failed
>
> Returned in 4 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `BAD_REQUEST_ERROR` | `business` | `payment_debit_response` | The transaction ID or amount sent does not match the original request. Please check the request details and retry. |
> | `BAD_REQUEST_ERROR` | `business` | `payment_response` | Payment was unsuccessful due to a temporary issue on our side. Any amount deducted will be refunded within 5-7 working days. |
> | `BAD_REQUEST_ERROR` | `internal` | `payment_response` | Payment failed due to a technical issue. Please try again or contact support if this continues. |
> | `BAD_REQUEST_ERROR` | `internal` | `payment_response` | Payment was unsuccessful due to a temporary issue on our side. Any amount deducted will be refunded within 5-7 working days. |

### Gateway Errors

Given below is the list of gateway errors.

> [accordion] account\_changed
>
> * **Description**: Your account information has changed. Please set up the mandate again with your current account.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] account\_restricted
>
> * **Description**: Payment failed due to a technical issue. Please contact support.
> * **Source**: `remitter_bank`
> * **Step**: `payment_credit_response`

> [accordion] account\_state\_blocked
>
> * **Description**: Your account is blocked or frozen. Please contact your bank to resolve this.
> * **Source**: `remitter_bank`
> * **Step**: `payment_debit_request`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] bank\_technical\_error
>
> Returned in 5 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank's system encountered an error. Please try again in a few moments. |
> | `GATEWAY_ERROR` | `upi_service` | `payment_debit_request` | Payment failed due to a technical issue. Please try again. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_authentication` | Your bank is temporarily unavailable. Please try again in a few moments. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_request` | Payment failed due to a technical issue. Please try again or contact support if this continues. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank is temporarily unavailable. Please try again later or use a different account. |

> [accordion] 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`

> [accordion] 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`

> [accordion] card\_not\_found
>
> * **Description**: Card record not found. Please contact your bank.
> * **Source**: `remitter_bank`
> * **Step**: `payment_response`

> [accordion] collect\_notification\_failed
>
> * **Description**: Payment failed as the collect notification expired. Please try again.
> * **Source**: `upi_service`
> * **Step**: `payment_response`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] customer\_psp\_fingerprint\_mismatch
>
> * **Description**: Payment failed due to a security check. Please try again from the same device.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] customer\_psp\_timeout
>
> * **Description**: Your UPI app took too long to respond. Please try again.
> * **Source**: `customer_psp`
> * **Step**: `payment_debit_response`

> [accordion] customer\_psp\_unavailable
>
> * **Description**: Your UPI app is currently unavailable. Please try again in a few moments.
> * **Source**: `customer_psp`
> * **Step**: `payment_response`

> [accordion] 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`

> [accordion] debit\_exceeds\_blocked\_amount
>
> * **Description**: Payment amount exceeds blocked amount. Please contact support.
> * **Source**: `remitter_bank`
> * **Step**: `payment_authentication`

> [accordion] 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`

> [accordion] declined\_by\_remitter\_bank
>
> Returned in 7 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `payee_psp` | `payment_response` | Your bank declined the payment setup. Please contact your bank or try a different account. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_debit_request` | Your bank declined the payment. Please contact your bank. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank declined the payment. This may be due to account restrictions. Please check with your bank or use another account |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_debit_response` | Payment failed due to a technical issue. Please try again or contact support if this continues. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank declined the payment. Please contact your bank. |
> | `GATEWAY_ERROR` | `payee_psp` | `payment_credit_response` | Payment was unsuccessful due to a temporary issue. Any amount deducted will be refunded within 5-7 working days. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_debit_response` | Your bank declined the payment. Please contact your bank. |

> [accordion] 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`

> [accordion] duplicate\_request
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `customer_psp` | `payment_response` | A duplicate payment request was detected. If the earlier payment was successful, no action is needed. Otherwise, please retry. |
> | `GATEWAY_ERROR` | `customer_psp` | `payment_request` | A mandate setup is already in progress. Please wait for it to complete or try again in a few moments. |

> [accordion] 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`

> [accordion] first\_transaction\_limit\_exceeded
>
> * **Description**: Payment declined as your first transaction is limited to ₹5,000. Please retry later.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] funds\_blocked\_for\_mandate
>
> * **Description**: Insufficient balance in your account. Please add funds and try again.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] incorrect\_pin\_entered
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `customer` | `payment_authentication` | Payment failed due to incorrect MPIN. Please retry with the correct MPIN. |
> | `GATEWAY_ERROR` | `customer` | `payment_response` | You've exceeded the number of PIN attempts. Please wait and try again later, or contact your bank if you've forgotten your PIN. |

> [accordion] insufficient\_funds
>
> * **Description**: Insufficient balance in your account. Please add funds and try again.
> * **Source**: `customer`
> * **Step**: `payment_debit_request`

> [accordion] 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`

> [accordion] invalid\_vpa
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `customer_psp` | `payment_authentication` | Payment was declined by your UPI app. Please try again or use a different method. |
> | `GATEWAY_ERROR` | `customer` | `payment_response` | Invalid UPI ID entered. Please enter a valid UPI ID and retry. |

> [accordion] mandate\_cancelled\_by\_user
>
> * **Description**: You cancelled the payment. Set it up again to complete your order.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] mandate\_not\_actioned\_by\_user
>
> * **Description**: Payment setup timed out. Please try again.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] mandate\_paused
>
> * **Description**: This UPI Autopay is paused. Please unpause it to continue payments with the business.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] mandate\_revoked
>
> * **Description**: This UPI Autopay was cancelled. Please set it up again.
> * **Source**: `customer`
> * **Step**: `payment_response`

> [accordion] merchant\_psp\_error
>
> * **Description**: Payment failed due to a technical issue. Please try again.
> * **Source**: `payee_psp`
> * **Step**: `payment_debit_response`

> [accordion] 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`

> [accordion] 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`

> [accordion] payee\_psp\_unavailable
>
> * **Description**: Payment failed due to a technical issue. Please try again or contact support if this continues.
> * **Source**: `payee_psp`
> * **Step**: `payment_response`

> [accordion] 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`

> [accordion] 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`

> [accordion] 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`

> [accordion] remitter\_bank\_throttling
>
> * **Description**: Your bank is experiencing high traffic. Please try again in a few moments.
> * **Source**: `remitter_bank`
> * **Step**: `payment_response`

> [accordion] remitter\_bank\_timeout
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_status_request` | Payment couldn't be completed due to a temporary issue. Any debited amount will be refunded in 4-5 business days. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Payment couldn't be completed due to a temporary issue. Any debited amount will be refunded in 4-5 business days. |

> [accordion] request\_not\_found
>
> * **Description**: Payment failed due to a technical issue. Please try again.
> * **Source**: `remitter_bank`
> * **Step**: `payment_response`

> [accordion] request\_timeout
>
> Returned in 3 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `upi_service` | `payment_authentication` | Payment timed out. Please try again. |
> | `GATEWAY_ERROR` | `upi_service` | `payment_request` | Payment failed as we didn't receive confirmation in time. Please try again. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_authentication` | Payment couldn't be completed due to a temporary issue. Any debited amount will be refunded in 4-5 business days. |

> [accordion] request\_validation\_failed
>
> Returned in 6 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `customer_psp` | `payment_response` | Payment failed due to a technical issue. Please try again or contact support if this continues. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank could not find this UPI Autopay mandate. Please set up the mandate again or contact support. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_request` | Payment failed due to a technical issue. Please try again or contact your bank if this continues. |
> | `GATEWAY_ERROR` | `customer_psp` | `payment_initiation` | Payment amount doesn't match UPI Autopay setup. Please contact support. |
> | `GATEWAY_ERROR` | `upi_service` | `payment_response` | Payment failed due to a technical issue. Please try again. |
> | `GATEWAY_ERROR` | `customer_psp` | `payment_status_request` | Payment failed due to a technical issue. Please contact support. |

> [accordion] risk\_declined\_by\_remitter\_bank
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Payment was declined for security reasons. Please contact your bank for assistance. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_initiation` | Payment was declined for security reasons. Please contact your bank for assistance. |

> [accordion] sequence\_mismatch
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `customer_psp` | `payment_response` | Payment failed due to a technical issue. Please try again. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Payment failed due to a technical issue. Please try again. |

> [accordion] signature\_corrupt
>
> * **Description**: Payment was declined for security reasons. Please contact your bank for assistance.
> * **Source**: `remitter_bank`
> * **Step**: `payment_response`

> [accordion] timeout\_at\_remitter\_bank
>
> Returned in 6 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank took too long to respond. Please try again. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Payment timed out due to a delay from your bank. Please try again in sometime. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Payment couldn't be completed due to a temporary issue. Any debited amount will be refunded in 4-5 business days. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_authentication` | Payment failed as we didn't receive a response in time. Please try again. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank is temporarily unavailable. Please try again in a few moments. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Your bank is processing its daily cut-off. Please try again after some time. |

> [accordion] transaction\_amount\_limit\_exceeded
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_authentication` | You've exceeded your total UPI spending limit. Please try again later or contact your bank to increase the limit. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | This amount is above your transaction limit. Please try a lower amount or contact your bank for assistance. |

> [accordion] 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`

> [accordion] validation\_failed\_at\_remitter
>
> Returned in 2 variants, depending on where the failure happens.
>
> | Error Code | Source | Step | Description |
> | - | - | - | - |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Payment failed due to a technical issue. Please try again. |
> | `GATEWAY_ERROR` | `remitter_bank` | `payment_response` | Payment failed due to a technical issue. Please try again or contact your bank if this continues. |

> [accordion] 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.

> [accordion] 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`

> [accordion] service\_unavailable
>
> * **Description**: Payment is temporarily unavailable. Please try again later.
> * **Source**: `internal`
> * **Step**: `payment_response`
