There are plenty of reasons for why a payout may fail. When that happens, a
takes place so that money is not mistakenly transferred.The error code that appears when you fire the API shows the source and the reason for the error. This payouts error codes documentation will help you understand the:
- .
- .
- .
Handy Tips
The error object in the payouts' API response gives more details about the exact reason for a payout failure and the suggested next steps. You can enable these changes from the RazorpayX Dashboard.
Please share this information with your developers and make sure to check if there is any hard mapping for parameters before making this change. Once enabled, these changes cannot be reversed.
Also take a look at the
to see how you can enhance your payout processes.Here is an example of how an error code appears when a payout fails.
The following table lists the error parameters and what they mean.
code
string The error code.
description
string A brief description of the error. For example, The account number field is required.
source
string Possible values:
gatewaybeneficiary_bankbusinessinternalKnow more about the reason for these error sources in the .
step
NA Not applicable for API Error Codes, value displayed to maintain consistency of error object.
reason
string The error reason. For example, input_validation_failed.
metadata
Null Value Not applicable for API Error Codes, value displayed to maintain consistency of error object.
field
string Details pertaining to the payout such as account_number, amount, payout purpose and so on.
The following table lists down the Payout Error Source and what it means.
| Source | Explanation |
|---|---|
gateway | Technical error at Razorpay Partner bank. |
beneficiary_bank | Technical error at beneficiary bank. |
business | Merchant action is required. |
internal | Technical error at Razorpay's server. |
The below table lists the error reasons and the explanation for why they occured. Find out how you can resolve the errors with the troubleshooting steps mentioned against the respective errors.
| Reason | Explanation | Next Step |
|---|---|---|
| gateway_technical_error | Technical error at Razorpay partner bank/NPCI/Wallet providers. This usually occurs when there is some server issue at the partner bank end. | Retry after some time or reach out to RazorpayX Support from the Dashboard. |
| beneficiary_bank_offline | Technical error at beneficiary bank. This usually occurs when there is some server issue at the beneficiary bank end. | Retry after some time or reach out to RazorpayX Support from the Dashboard. |
| beneficiary_psp_offline | Technical error at beneficiary payment service provider. This usually occurs when there is some server issue at beneficiary bank end. | Retry after some time or reach out to RazorpayX Support from the Dashboard. |
| bank_account_invalid | Incorrect beneficiary bank account number. | Correct the account number and retry. |
| bank_account_closed | Payout failed as the beneficiary account is closed. | Check with your contact or reach out to RazorpayX Support from the Dashboard. |
| bank_account_dormant | Payout failed as beneficiary account is dormant. | Contact the beneficiary bank. |
| transaction_limit_exceeded | Payout amount is greater than the limit supported by the beneficiary account. | Check fund transfer limit for the beneficiary bank and retry. |
| beneficiary_bank_failure | Technical error at beneficiary bank. This usually occurs when there is some server issue at beneficiary bank end. | Retry after some time or reach out to RazorpayX Support from the Dashboard. |
| beneficiary_bank_rejected | Payout rejected by beneficiary bank. Please contact the beneficiary bank. | Check with beneficiary bank or reach out to RazorpayX Support from the Dashboard. |
| bank_account_frozen | Payout failed as the beneficiary account is frozen. | Check with the beneficiary bank. |
| gateway_pending | Payout pending at Razorpay partner bank/NPCI/Wallet providers. | Status will be updated after 48 working hours. |
| gateway_timeout | Technical error at Razorpay partner bank/NPCI/Wallet providers. This usually occurs when there is some server issue at the partner bank end. | Retry after some time or reach out to RazorpayX Support from the Dashboard. |
| imps_not_allowed | IMPS is not enabled on beneficiary account. | Retry with different mode for fund transfer. |
| invalid_ifsc_code | Payout failed as the IFSC is invalid. | Correct the IFSC and retry. |
| nre_bank_account | Payout failed as beneficiary account is an NRE account. | Contact the beneficiary bank. |
| beneficiary_vpa_invalid | Payout failed due to invalid beneficiary VPA/UPI ID. | Correct the VPA/UPI ID and retry. |
| server_error | Technical error. This usually occurs when there is some issue with the server. | Retry after some time or reach out to RazorpayX Support from the Dashboard. |
| input_validation_failed | For error description The account number field is required | Ensure you pass the request body in correct format. Refer to . |
| input_validation_failed | For error description Minimum transaction amount should be 100 paise | Ensure the amount field has value >=100 as this field expects amount in paise format. |
| input_validation_failed | For error description The id provided does not exist | Ensure the fund account is already added and you pass the correct Fund Account ID. |
| input_validation_failed | For error description Payout mode is invalid | This is a case sensitive field and you must pass this mode as it is. For example, IMPS, RTGS, UPI, NEFT. |
| Not Applicable | For error description The RazorpayX Account number is invalid. | Pass the correct debit account number. You can check the account number from your → My Account & Settings → Banking → Account No. Also confirm if you are using test API keys for test account number and live API Keys for RazorpayX Lite or Current account number. |