Error Types
Explore the RazorpayX Error Codes and know how to troubleshoot and understand them.
RazorpayX aims to make all transactions successful for its customers. Even then, errors might still occur in the financial ecosystem due to intermittent communication and technical issues at multiple levels.
In RazorpayX, you can identify error codes at the source of the response, along with the reason for such errors. This will help in minimising the errors reducing the losses.
- : These are returned to you when the API does not fire as expected.
- : These are returned when an error occurs during contact creation.
- : These are returned when Fund Account creation fails.
- : These provide the reason for a payouts' state and the next steps to be taken. These are returned in the API response and webhook payloads and are available on the dashboard.
Error codes can help you build your own logic and take further remedial action at your end, wherever possible. Deriving these insights can help your business to:
- Map and analyse top failure reasons.
- Identify the source of failure.
- Narrow down and understand the cause of the failure (could be due to actions taken by your contact or external factors such as the beneficiary bank or network connectivity).
- Identify the exact reason of the failure.
- Handle actionable error codes.
- Avoid possible integration errors.
API error codes are sent to you when an API cannot be fired. All successful Razorpay API responses return with HTTP Status code 200.
Razorpay Errors API identifies two types of errors:
- Business: Errors where merchant action is required.
- Internal: Technical errors at Razorpay's server.
In case of a failure, we return a JSON error response that contains the reason for the failure. You can use this response to make changes to the API request body and try to fire them again.
Check
to understand the reason and troubleshooting procedure.API errors appear in the format shown below. You can refer to the
to resolve them.Here is an example of how an error code appears when an API does not fire.
{"error": {"code": "BAD_REQUEST_ERROR","description": "The account number field is required","source": "business","step": "null","reason": "input_validation_failed","metadata": {},"field": "account_number"}}
code
string Type of the error. For example, BAD_REQUEST_ERROR.
description
string A description for the error. For example, The id provided does not exist.
source
string Possible values:
business: Merchant action required.internal: Technical error at Razorpay's server.
reason
string The error reason. For example, input_validation_failed.
step
NA Not applicable for API Error Codes, value displayed to maintain consistency of error object.
metadata
Null value Not applicable for API Error Codes, value displayed to maintain consistency of error object.
The below tables lists the API error reasons and the steps to fix them.
Given below is a list of HTTP error codes, reasons and next steps to fix them.
- Error Description: Payout is not in pending state and cannot be approved or rejected.
- Source: business
- Reason:
payout_approval_not_allowed - Next Steps: Payout approval is no longer required. No further action required.
- Source: business
- Reason:
authentication_failed - Next Steps: Please check the OAuth token being used and retry again.
5xx errors occur when servers fail to connect causing network issues during an ongoing payout process. The
is specifically built to handle such network issues. In case of any network issue like timeouts/5xx, you can safely fire the same request again using the same idempotency key and the request body as the original timed out request within 7 calendar days. Razorpay will ensure that the request does not get processed again if it has already been processed on our end.If the payout was created in the first request to the RazorpayX system using the same idempotency key, you get the created payout details along with the current
in the response to the new request.Watch Out!
The current status of the payout can be returned as pending processing or failed.
- When retrying a request, the must be the same as the first request for idempotency to work. A different payload will be rejected as a
BAD_REQUEST. - If the payout gets created in the new request, you will receive the payout details with the current status in response to the new request.
- If the retry request times out, you can again retry using the same idempotency key. We recommend doing 3 retries at an interval of 1, 2 and 5 mins for each retry.
If 5XX error is received on the request or retried request:
- Check the status of payout using
reference_id(the samereference_idyou passed as part of the request) after 5 minutes using up to 1 hour from payout creation time, in case you do not receive webhook within 5 minutes. - If you do not receive any status for the payouts using Fetch Payout API for the reference ID provided after 1 hour, then
failthe payout after 1 hour.
Handy Tips
After 3 retries, there will be no payout for 1 hour.
We recommend you to enable webhooks so that you are alerted of the status updates in any process. By enabling alerts for errors, you can reduce the delay in troubleshooting.
- You can to configure and receive instant notifications.
- They are sent whenever a specific occurs.
- When the configured events are triggered, we send an HTTP POST in JSON to the webhook's configured URL.
Was this page helpful?