Skip to main content
Available in🇮🇳 India
The Accounts APIs use conventional HTTP status codes:
  • 2xx: Success
  • 4xx: A problem with the request or the sub-merchant’s data
  • 5xx: A problem on Razorpay’s side
Each endpoint page lists the errors it returns. A value that fails verification is not an error. The call succeeds, the element’s verification shows rejected with an error_code and its requirement is due again. See Failed-Check Codes.

Error Object

Every error response carries the same envelope. Branch on reason, show description to the sub-merchant and use field to point at the value. Errors never repeat a value you sent.
The error object has the following parameters:
object
The error details.
string
The error class. Possible values:
  • BAD_REQUEST_ERROR: Fix the request or the sub-merchant’s data. Do not retry unchanged.
  • SERVER_ERROR: A problem on Razorpay’s side or a verification provider’s. Retry the same request. It does not act twice.
string
A sentence to show the sub-merchant. It never repeats a value you sent or anything Razorpay holds about the business. Neither does metadata. field names the value instead.
string
Where the error came from, which decides what to do next. Possible values:
  • business: Your request or the sub-merchant’s data: a missing field or a bad format, such as reason: invalid_format at step: validation. Fix the request or ask the sub-merchant to correct the value, then send it again. Retrying unchanged fails the same way.
  • verification_provider: A registry or bank that Razorpay calls did not answer. For example, the Central KYC Records Registry (CKYC) may not answer when an action sends a code. The call then returns 503 with provider_unavailable. Nothing is wrong with the data, so retry later. A check inside an update does not fail the call. Razorpay saves the value, and its verification shows rejected with a code such as pan_check_unavailable.
  • internal: A problem inside Razorpay (reason: internal_error). Retry. A write retried with the same X-Idempotency-Key does not act twice.
string
The onboarding step, such as validation (the request’s own checks), document_upload or ckyc_otp.
string
A stable, machine-readable reason. Each endpoint page lists the reasons the endpoint returns and when. See API Errors.
string
The request field or account path the error is about.
object
Structured hints, such as allowed_values on invalid_option. {} when the error has no hints.

API Errors

Razorpay can add new reasons. Handle an unknown reason by its HTTP status.
Code: 400Reason: invalid_requestThe request has one of these problems:
  • The body is not valid JSON.
  • A required field is missing.
  • A key is not one the endpoint takes, such as a misspelled or read-only field.
Returned by:Solution: Send valid JSON with every required field. Remove any key the endpoint does not take, such as a misspelled or read-only field.
Code: 400Reason: invalid_formatA value does not match its format or range, such as:
  • A PAN that does not match its pattern
  • A phone that is not +91 and 10 digits
  • A count above 100
  • A file_id that is not file_ followed by 14 letters or digits
  • An X-Idempotency-Key that is not 16-64 printable ASCII characters
Returned by:Solution: Correct the value named in error.field and send it again. metadata.pattern shows the expected format. metadata.minimum and metadata.maximum show the range.
Code: 400Reason: invalid_optionA value is not one of the allowed options.Returned by:Solution: Send one of the allowed values. metadata.allowed_values lists them when the list is short.
Code: 400Reason: missing_headerA required header is missing or malformed. metadata.header names it.Returned by:Solution: Send the header named in metadata.header. On a write, send X-Idempotency-Key with 16-64 printable ASCII characters.
Code: 400Reason: step_not_dueThe value or action is not due yet or not due at all. An example is a bank account sent before the business type.Returned by:Solution: Send only what the requirements list. metadata.due lists what is due now.
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: invalid_file_nameThe file name has characters that are not allowed, such as a path separator or a control character.Returned by:Solution: Rename the file without path separators or control characters, then upload it again.
Code: 400Reason: file_name_too_longThe file name is longer than 255 characters.Returned by:Solution: Shorten the file name to 255 characters or fewer, 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: 400Reason: idempotency_key_reusedYou used this X-Idempotency-Key in the last 24 h with a different body. For an upload, the key is bound to its type and file for 1 h.Returned by:Solution: Send a new X-Idempotency-Key for a different request. Reuse a key only to retry the same request.
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 you revoke it or its rotation window ends.Returned by: Every endpoint.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: Every endpoint.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: Every endpoint.Solution: Send requests from an IP range on your app’s allowlist for this mode. To use another range, add it to the allowlist on the Partner Dashboard.
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. Calls on it never succeed again for your platform.
Code: 404Reason: not_foundThe resource does not exist or the account is not mapped to your app in this mode. Both look the same, so an ID cannot reveal who banks with Razorpay. field names the ID.Returned by:Solution: Check the ID in error.field. Use the ID of an account or document of your app, in the same mode as your key.
Code: 409Reason: field_lockedThe value cannot change in the product’s current status. field names it and metadata.status is the status that locks it.Returned by:Solution: Tell the sub-merchant that this detail cannot change now. metadata.status names the status that locks it.
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.
Code: 413Reason: file_too_largeThe file is larger than 20 MB. metadata.max_bytes is the limit.Returned by:Solution: Upload a file of 20 MB or less. metadata.max_bytes is the limit in bytes.
Code: 415Reason: unsupported_media_typeThe request has one of these problems:
  • The upload body is not multipart/form-data. error.field is Content-Type.
  • The file format is not accepted for its document type. Razorpay detects the format from the file content, not its name. error.field is file.
Returned by:Solution: Send the body as multipart/form-data. Upload the file in a format listed in metadata.accept. metadata.detected_type shows the format found.
Code: 429Reason: rate_limitedYour app sent more requests than its rate limit allows.Returned by: Every endpoint.Solution: Wait for the time in the Retry-After header, then retry.
Code: 500Reason: internal_errorSomething went wrong inside Razorpay.Returned by: Every endpoint.Solution: Retry the request. A write retried with the same X-Idempotency-Key does not act twice.
Code: 503Reason: provider_unavailableA registry, bank or SMS or email provider that an action calls did not answer. Nothing ran and nothing is wrong with the request. Checks inside an update never fail the call this way.Returned by:Solution: Retry after the time in the Retry-After header. Nothing is wrong with the request.

Failed-Check Codes

A failed check does not fail the call. The element’s verification.status is rejected with the code in verification.error_code. Its requirement comes back due, with a requirement_reason. Branch on the code and show verification.error_description to the sub-merchant. Keep these points in mind:
  • The link codes link_expired, video_kyc_failed, digilocker_failed and upi_payment_failed have no element to carry them. The action comes back due. Running it creates a new link.
  • A phone or email One-Time Password (OTP) carries no failed-check code. After a wrong code, phone_otp or email_otp stays due. An expired code or 3 wrong tries bring back send_phone_otp or send_email_otp.
  • Razorpay never returns the bank’s or registry’s own record, such as the account holder’s name. The code says what did not match.
Error code: pan_not_foundCheck: PANThe PAN registry has no such PAN or rejected it as invalid.Fields:
  • business_profile.authorized_person.identity_numbers.individual_pan
  • business_profile.identity_numbers.business_pan
  • business_profile.stakeholders.<stakeholder_id>.identity_numbers.individual_pan
Next step: The PAN again, or the PAN card, as the options of one composite requirement.
Error code: pan_name_mismatchCheck: PANThe PAN exists, but its holder is not the signatory named for the company.Fields:
  • business_profile.authorized_person.identity_numbers.individual_pan
Next step: The signatory’s name and PAN again.
Error code: pan_check_unavailableCheck: PANThe PAN registry did not answer or answered with an error. Nothing is wrong with the PAN.Fields:
  • business_profile.authorized_person.identity_numbers.individual_pan
  • business_profile.identity_numbers.business_pan
Next step: The PAN card; or send the PAN again later.
Error code: promoter_underageCheck: PANThe PAN holder is under 18.Fields:
  • business_profile.authorized_person.identity_numbers.individual_pan
  • business_profile.authorized_person.documents.individual_pan_document
Next step: Nothing the platform can send clears it; the sub-merchant contacts Razorpay.
Error code: pan_card_mismatchCheck: PAN cardThe PAN printed on the card is not the PAN sent.Fields:
  • business_profile.authorized_person.documents.individual_pan_document
Next step: The PAN card again.
Error code: pan_card_name_mismatchCheck: PAN cardThe name on the card is not the owner’s or signatory’s.Fields:
  • business_profile.authorized_person.documents.individual_pan_document
Next step: The PAN card again.
Error code: pan_card_name_unreadableCheck: PAN cardRazorpay could not read a name or number off the card.Fields:
  • business_profile.authorized_person.documents.individual_pan_document
Next step: The PAN card again.
Error code: not_a_pan_cardCheck: PAN cardThe file is not a PAN card.Fields:
  • business_profile.authorized_person.documents.individual_pan_document
Next step: The PAN card again.
Error code: otp_invalidCheck: CKYC codeThe CKYC code does not match the one sent.Fields:
  • business_profile.authorized_person.identity_numbers.individual_ckyc
Next step: The corrected code in otp, with the same request_id: ckyc_otp and ckyc_request_id stay due.
Error code: otp_expiredCheck: CKYC codeThe CKYC code was right but has expired. A wrong code tried 3 times also expires.Fields:
  • business_profile.authorized_person.identity_numbers.individual_ckyc
Next step: send_ckyc_otp again, for a new code: the send action is due again.
Error code: ckyc_unavailableCheck: CKYCRazorpay could not download the CKYC record, for a system reason.Fields:
  • business_profile.authorized_person.identity_numbers.individual_ckyc
Next step: The proof of address (Aadhaar, passport or voter ID).
Error code: poa_name_mismatchCheck: Proof of addressThe address proof is not in the person’s name.Fields:
  • business_profile.authorized_person.documents.aadhaar_front
  • business_profile.authorized_person.documents.voter_id_front
  • business_profile.authorized_person.documents.passport_front
  • business_profile.stakeholders.<stakeholder_id>.documents.aadhaar_front
  • business_profile.stakeholders.<stakeholder_id>.documents.voter_id_front
  • business_profile.stakeholders.<stakeholder_id>.documents.passport_front
Next step: The proof of address again.
Error code: poa_unreadableCheck: Proof of addressRazorpay could not read the address proof.Fields:
  • business_profile.authorized_person.documents.aadhaar_front
  • business_profile.authorized_person.documents.voter_id_front
  • business_profile.authorized_person.documents.passport_front
  • business_profile.stakeholders.<stakeholder_id>.documents.aadhaar_front
  • business_profile.stakeholders.<stakeholder_id>.documents.voter_id_front
  • business_profile.stakeholders.<stakeholder_id>.documents.passport_front
Next step: The proof of address again.
Error code: bank_name_mismatchCheck: Bank accountThe account holder’s name does not match the PAN name or the business name.Fields:
  • bank_accounts.settlements_primary
Next step: Another account, or a ₹1 UPI payment from it, as the options of one composite requirement.
Error code: bank_details_incorrectCheck: Bank accountThe account number or Indian Financial System Code (IFSC) is wrong.Fields:
  • bank_accounts.settlements_primary
Next step: The account again, or a ₹1 UPI payment from it.
Error code: bank_account_unusableCheck: Bank accountThe bank reported the account frozen, blocked, closed or Non-Resident External (NRE).Fields:
  • bank_accounts.settlements_primary
Next step: A different account, or a ₹1 UPI payment from one.
Error code: bank_check_unavailableCheck: Bank accountRazorpay could not reach the bank. Nothing is wrong with the account.Fields:
  • bank_accounts.settlements_primary
Next step: The bank_account composite requirement again: the account, or a ₹1 UPI payment from it.
Error code: bank_not_verifiedCheck: Bank accountAny other failure. Razorpay does not say why.Fields:
  • bank_accounts.settlements_primary
Next step: The account again, or a ₹1 UPI payment from it.
Error code: gstin_name_mismatchCheck: Goods and Services Tax Identification Number (GSTIN)The GSTIN is registered to another business.Fields:
  • business_profile.identity_numbers.gstin
Next step: The GSTIN again, or the Udyam number.
Error code: gstin_not_foundCheck: GSTINThe GST registry has no such GSTIN or the GSTIN is cancelled.Fields:
  • business_profile.identity_numbers.gstin
Next step: The GSTIN again, or the Udyam number.
Error code: udyam_name_mismatchCheck: Udyam numberThe Udyam registration is in another business’s name.Fields:
  • business_profile.identity_numbers.udyam_registration
Next step: The Udyam number again, or the GSTIN.
Error code: udyam_not_foundCheck: Udyam numberThe Udyam registry has no such number.Fields:
  • business_profile.identity_numbers.udyam_registration
Next step: The Udyam number again, or the GSTIN.
Error code: website_unreachableCheck: WebsiteRazorpay could not open the website, or it is not live.Fields:
  • products.payment_gateway.payment_channels.website.primary
Next step: The website again.
Error code: video_kyc_failedCheck: Video KYCThe agent could not verify the person on the call. For example, the face did not match the PAN photo or the call dropped.Actions:
  • create_video_kyc_link
Next step: The action is due again: run it for a new call.
Error code: digilocker_failedCheck: DigiLockerThe sub-merchant declined to share the Aadhaar in DigiLocker or DigiLocker returned no Aadhaar.Actions:
  • create_aadhaar_digilocker_link
Next step: The action is due again: run it for a new link, or send a proof-of-address document, another option of the same composite requirement.
Error code: upi_payment_failedCheck: UPI ₹1 paymentThe ₹1 payment failed or did not come from an account in the business’s or owner’s name.Actions:
  • create_upi_link
Next step: The action is due again: run it for a new link, or send the account.

Review Reasons

In needs_clarification, each point a reviewer flags comes back as a requirement, with the reviewer’s reason in requirement_reason. Answer the requirements listed. Then send submit_clarification in a call of its own with Update an Account.
Reason: bank_account_ownership_unconfirmedFlagged requirement: bank_accountThe reviewer could not confirm that the business or its owner holds the settlement account.Fields:
  • bank_accounts.settlements_primary
Reason: website_no_productsFlagged requirement: websiteThe website does not list products or prices.Fields:
  • products.payment_gateway.payment_channels.website.primary
Reason: website_policies_missingFlagged requirement: websiteThe website has no refund, cancellation or contact policy.Fields:
  • products.payment_gateway.payment_channels.website.primary
Reason: business_proof_unclearFlagged requirement: proof_of_businessThe registration document is unreadable, expired or in another name.Fields:
  • business_profile.documents.<type>
Reason: address_proof_unclearFlagged requirement: proof_of_address_for_individualThe proof of address is unreadable, cropped or in another name.Fields:
  • business_profile.authorized_person.documents.<type>
Reason: category_mismatchFlagged requirement: None. The reviewer flags the business category.What the business sells does not match its category.Fields:
  • business_profile.business_category
Last modified on November 18, 2026