Skip to main content
Available in🇮🇳 India
The Merchant Risk APIs use the error object and the HTTP status codes of the Accounts API:
  • 2xx: Success
  • 4xx: A problem with the request or the account’s state
  • 5xx: A problem on Razorpay’s side
Repeating the current state with a partner action is not an error. It returns 200 and changes nothing.

Error Object

Every error response carries the same envelope with 7 fields. Branch on reason and use field to point at the value. Show description to the sub-merchant only for the state errors: payments_disable_not_reversible, settlement_disable_not_reversible, suspension_not_reversible and product_suspended. metadata is empty unless an error names its keys.
Failure

Partner Action Errors

These errors are specific to partner actions. Razorpay can add new reasons. Handle an unknown reason by its HTTP status.
Code: 400Reason: field_read_onlyThe body sets a field that only Razorpay sets, such as status_reason.requirement_id. initiated_by and updated_at are also read-only.Returned by:Solution: Send only status_reason.code and status_reason.description. error.field names the read-only field.
Code: 400Reason: payments_disable_not_reversibleYou called enable_payments while payment_acceptance.initiated_by is razorpay.Returned by:Solution: Show the sub-merchant status_reason.description. If status_reason.requirement_id is set, answer that requirement. metadata.requirement_id repeats it.
Code: 400Reason: settlement_disable_not_reversibleYou called enable_settlement while settlement.initiated_by is razorpay.Returned by:Solution: Show the sub-merchant status_reason.description. If status_reason.requirement_id is set, answer that requirement. metadata.requirement_id repeats it.
Code: 400Reason: suspension_not_reversibleYou called unsuspend on a product that Razorpay suspended.Returned by:Solution: Show the sub-merchant status_reason.description from either object. Answer the requirement in status_reason.requirement_id, if any.
Code: 400Reason: product_suspendedYou called disable_payments, enable_payments, disable_settlement or enable_settlement while the product’s status is suspended.Returned by:Solution: Reverse the suspension first if you set it, with unsuspend. A suspension by Razorpay can only be reversed by Razorpay.
Code: 403Reason: partner_actions_not_enabledYou called suspend, disable_payments or disable_settlement, and Razorpay has not switched on partner actions for your platform. Reversing your own action (unsuspend, enable_payments, enable_settlement) is never refused for this reason.Returned by:Solution: Contact Razorpay to switch on partner actions for your platform.

Partner Action Request Errors

These follow the Accounts API actions conventions.
Code: 400Reason: invalid_account_idThe account ID in the path is not acc_ followed by 14 letters or digits.Returned by:Solution: Send the account ID as acc_ followed by 14 letters or digits, such as acc_Rk9Xm2Qp7Zt4Nb.
Code: 400Reason: invalid_formatX-Idempotency-Key is not 16-64 printable ASCII characters.Returned by:Solution: Send X-Idempotency-Key with 16-64 printable ASCII characters.
Code: 400Reason: invalid_optionaction is not one of the supported actions. metadata.allowed_values lists the values.Returned by:Solution: Send an action from metadata.allowed_values.
Code: 400Reason: idempotency_key_reusedYou sent this X-Idempotency-Key before with a different action or different inputs.Returned by:Solution: Send a new X-Idempotency-Key for a different request. Reuse a key only to retry the same request.

Fetch a Requirement Errors

Code: 404Reason: requirement_not_foundNo requirement with this requirement_id is on the account’s payment_gateway product.Returned by:Solution: Check the ID in error.field. Use the id of a requirement on this account.

Upload Errors

Code: 400Reason: invalid_requestThe request has one of these problems:
  • The body is not multipart/form-data.
  • file or document_type is missing.
  • The request has more than 1 file.
  • document_type in the body is not the one in the path.
Returned by:Solution: Send a multipart/form-data body with 1 file and the same document_type as the path.
Code: 400Reason: invalid_optiondocument_type is not a document type.Returned by:Solution: Send the requirement’s requirement_code, or another valid document type.
Code: 400Reason: invalid_fileRazorpay cannot read the file. For example, the PDF is truncated or corrupt.Returned by:Solution: Check that the file is complete and readable, then upload it again.
Code: 400Reason: password_protected_fileThe file is password protected.Returned by:Solution: Remove the password from the file, then upload it again.
Code: 413Reason: file_too_largeThe file is larger than 20 MB.Returned by:Solution: Compress or split the file to 20 MB or less, then upload it again.
Code: 415Reason: unsupported_media_typeThe file is not a PDF, JPEG or PNG. metadata.detected_type names the type Razorpay found.Returned by:Solution: Convert the file to PDF, JPEG or PNG, then upload it again.

Write Request Errors

These errors are returned by the write endpoints listed under each.
Code: 400Reason: missing_headerX-Idempotency-Key is missing. On answers and uploads, a key that is not 16-64 printable ASCII characters also returns this. On partner actions, such a key returns invalid_format.Returned by:Solution: Send X-Idempotency-Key with 16-64 printable ASCII characters.
Code: 409Reason: idempotency_key_mismatchYou used this X-Idempotency-Key in the last 24 h with a different body or file.Returned by:Solution: Send a new X-Idempotency-Key for a different request. Reuse a key only to retry the same request.
Code: 409Reason: idempotency_in_progressA request with this X-Idempotency-Key is still running. Razorpay stores its result only when it finishes.Returned by:Solution: Wait for the time in the Retry-After header, then retry with the same key.

Common Errors

Every endpoint returns these errors.
Code: 401Reason: invalid_credentialsThe Authorization header is missing or is not Basic. Other causes are a key that is not a partner key or a wrong secret. A secret also stops working when it is revoked or its rotation window ends.Returned by:Solution: Send your partner key and secret as HTTP Basic credentials. Check that the secret is current for the key.
Code: 403Reason: onboarding_not_enabledYour app does not have access to the Onboarding APIs in this mode. Razorpay may also have turned off your app’s access.Returned by:Solution: Contact Razorpay to get access to the Onboarding APIs for your app in this mode.
Code: 403Reason: ip_not_allowedThe request came from an IP address outside your app’s allowlist for its mode. Test mode checks the allowlist once it has an entry.Returned by:Solution: Send requests from an IP range on your app’s allowlist for this mode.
Code: 403Reason: insufficient_scopeYour key and secret pair does not have the scope the endpoint needs: onboarding_accounts_read to fetch, onboarding_accounts_write for partner actions and answers, onboarding_documents_write to upload.Returned by:Solution: Use a key and secret pair with a scope listed in metadata.required_scopes.
Code: 403Reason: consent_withdrawnThrough Razorpay, the sub-merchant withdrew your permission to act on the account. Calls on this account never succeed again for your platform.Returned by:Solution: Stop calling this account and update your records.
Code: 404Reason: not_foundNo account with this ID is mapped to your app in this mode. The account does not exist, belongs to another platform or belongs to a direct Razorpay merchant. It can also be a test account called in live mode.Returned by:Solution: Check the ID in error.field. Use the ID of an account mapped to your app, in the same mode as your key.
Code: 429Reason: rate_limitedYour app sent more requests than its rate limit allows.Returned by:Solution: Wait for the time in the Retry-After header, then retry.
Code: 500Reason: internal_errorSomething went wrong inside Razorpay.Returned by:Solution: Retry the request. A write retried with the same X-Idempotency-Key does not act twice.
Last modified on November 20, 2026