About Error Codes

Explore the RazorpayX Error Codes and know how to troubleshoot and understand them.

Understanding error codes can help in identifying those errors and troubleshooting them. This page describes the error codes returned when you fire Fund Account APIs.

In RazorpayX, you can identify error codes at the source of the response, along with the reason for such errors.

  • : 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.

Watch Out!

The error object for payouts will soon be deprecated. Please move to Payout status details, to understand the status of your payout and take the necessary next steps in case on an error. You can continue using error object for other APIs.

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.

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.

It is critical for businesses to identify the source of the error and the reason for the error. This will help in minimising the errors reducing the losses.

API error codes are sent to you when an API cannot be fired. All successful Razorpay API responses return with HTTP Status code 200.

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 the various types of errors and the explanation for where and why they occur.

Razorpay Errors API identifies two types of errors:

  • Business
  • Internal

These errors appear at a source, and with a reason that explains the error. The following table explains the reasons.

businessMerchant action required.
internalTechnical error at Razorpay's server.

API errors appear in the format explained in the

. You can refer to the to resolve them.

Here is an example of how an error code appears when an API does not fire.


string Type of the error. For example, BAD_REQUEST_ERROR.


string A description for the error. For example, The id provided does not exist.


string Possible values:

  • business: Merchant action required.
  • internal: Technical error at Razorpay's server.


string The error reason. For example, input_validation_failed.


NA Not applicable for API Error Codes, value displayed to maintain consistency of error object.


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.

Error DescriptionNext Steps
The requested URL was not found on the server.Occurs when wrong URL or HTTPS method is passed. Enter the correct URL as per the respective API request. Know more about . If the issue persists, .
Transactions from this IP are not allowed. Contact support for help.Occurs when the API call is sent from an IP whose server/node is not allowlisted. Always .
Different request body sent for the same Idempotency Header.Occurs when the system receives a different payout request body for an existing idempotent header. Ensure that every payout body has a .
We are facing some trouble completing your request at the moment. Please try again shortly.Occurs in exceptional cases when there is a server issue at Razorpay's end. Retry safely using an or .

The below table lists HTTP error codes, reasons and next steps to fix them. Scroll the table sideways to see more.

HTTP CodeError CodeError DescriptionSourceReasonNext Steps
400BAD_REQUEST_ERRORPayout is not in pending state and cannot be approved or rejectedbusinesspayout_approval_not_allowedPayout approval is no longer required. No further action required.
401BAD_REQUEST_AUTHENTICATION_ERRORThe OAuth token used in the request was invalid or has expiredbusinessauthentication_failedPlease check the OAuth token being used and retry again.
401BAD_REQUEST_AUTHENTICATION_ERRORThe OAuth token used does not have sufficient permissions for this requestbusinessauthentication_failedPlease 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.

Handy Tips

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:

  1. Check the status of payout using reference_id (the same reference_id you 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.
  2. If you do not receive any status for the payouts using Fetch Payout API for the reference ID provided after 1 hour, then fail the 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?