2xx: Success4xx: A problem with the request or the account’s state5xx: A problem on Razorpay’s side
200 and changes nothing.
Error Object
Every error response carries the same envelope with 7 fields. Branch onreason 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.
Partner Action Errors
These errors are specific to partner actions. Razorpay can add new reasons. Handle an unknown reason by its HTTP status.This field can't be changed.
This field can't be changed.
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.Razorpay disabled payment acceptance. Only Razorpay can enable it.
Razorpay disabled payment acceptance. Only Razorpay can enable it.
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.Razorpay put settlement on hold. Only Razorpay can release it.
Razorpay put settlement on hold. Only Razorpay can release it.
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.Razorpay suspended the product. Only Razorpay can unsuspend it.
Razorpay suspended the product. Only Razorpay can unsuspend it.
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.The product is suspended. Reverse the suspension first.
The product is suspended. Reverse the suspension first.
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.Partner actions aren't enabled for this platform.
Partner actions aren't enabled for this platform.
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.The account ID isn't valid.
The account ID isn't valid.
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.The idempotency key isn't valid.
The idempotency key isn't valid.
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.Choose one of the allowed values (action).
Choose one of the allowed values (action).
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.This idempotency key was already used with a different request.
This idempotency key was already used with a different request.
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
The requirement doesn't exist on this account.
The requirement doesn't exist on this account.
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
The request is missing a required field.
The request is missing a required field.
400Reason: invalid_requestThe request has one of these problems:- The body is not
multipart/form-data. fileordocument_typeis missing.- The request has more than 1 file.
document_typein the body is not the one in the path.
multipart/form-data body with 1 file and the same document_type as the path.Choose one of the allowed values (document type).
Choose one of the allowed values (document type).
400Reason: invalid_optiondocument_type is not a document type.Returned by:Solution: Send the requirement’s requirement_code, or another valid document type.The file can't be read. Upload it again.
The file can't be read. Upload it again.
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.Upload the file without a password.
Upload the file without a password.
400Reason: password_protected_fileThe file is password protected.Returned by:Solution: Remove the password from the file, then upload it again.The file is too large.
The file is too large.
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.Upload a PDF, JPEG or PNG file.
Upload a PDF, JPEG or PNG file.
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.A required header is missing.
A required header is missing.
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.This request conflicts with an earlier one.
This request conflicts with an earlier one.
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.The earlier request is still being processed.
The earlier request is still being processed.
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.The credentials aren't valid.
The credentials aren't valid.
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.Onboarding isn't enabled for this platform.
Onboarding isn't enabled for this platform.
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.Requests from this address aren't allowed.
Requests from this address aren't allowed.
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.These credentials can't perform this operation.
These credentials can't perform this operation.
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.The business has withdrawn this platform's access to its Razorpay account.
The business has withdrawn this platform's access to its Razorpay account.
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.The requested resource doesn't exist.
The requested resource doesn't exist.
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.Too many requests. Try again shortly.
Too many requests. Try again shortly.
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.Something went wrong on our side. Try again.
Something went wrong on our side. Try again.
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.