Skip to main content
Available in🇮🇳 India
This page lists every reason an Onboarding API can return. Each comes with its HTTP status, its source and how to trigger it in test mode. Branch on error.reason. error.description is display text and can change.
Handy TipsA failed check is not an error. The call returns 200, with the element’s verification.status: rejected and a verification.error_code. See 2. Failed Checks and the Test Values.

1. API Errors

Every API error returns the same error object. Read error.reason and error.field to decide what to do. Know more about Onboarding API errors. The table below lists every API error, sorted by HTTP status:
HTTPerror.reasonerror.code, error.source and error.stepWhenThrown byHow to trigger in test modeTest mode
400file_name_too_longBAD_REQUEST_ERROR
business
document_upload
The file name is longer than 255 characters.UploadA file name of 256 characters.Available
400invalid_document_urlBAD_REQUEST_ERROR
business
document_download
A document url is not HTTPS, or it points or redirects to a private, loopback or cloud-metadata address. It also fires when the file could not be downloaded or failed the upload checks.Create, UpdateA document url of https://10.0.0.1/a.pdf.Available
400invalid_fileBAD_REQUEST_ERROR
business
document_upload
The file cannot be read, such as a truncated or corrupt PDF.UploadA truncated PDF.Available
400invalid_file_nameBAD_REQUEST_ERROR
business
document_upload
The file name has characters that are not allowed, such as a path separator or a control character.UploadA file name with /.Available
400invalid_formatBAD_REQUEST_ERROR
business
validation
A value does not match its format or range. Examples are a PAN pattern, a phone that is not +91 and 10 digits or a count above 100. metadata.pattern or metadata.minimum and metadata.maximum say what is expected.Create, List, Update, ActionsPAN ABC123, a phone without +91 or a code of 5 digits.Available
400invalid_optionBAD_REQUEST_ERROR
business
validation
A value is not one of the allowed options. metadata.allowed_values lists them when the list is short.Create, List, Update, Actions, Upload, List documentsbusiness_type: "company", or action send_sms_otp.Available
400invalid_requestBAD_REQUEST_ERROR
business
validation
The body is not valid JSON, a required field is missing or a key is not one the operation takes. An example is a misspelled or read-only field.Create, List, Update, Actions, UploadLeave out user when creating an account. Send verification in an update.Available
400missing_headerBAD_REQUEST_ERROR
business
validation
A required header is missing or malformed. metadata.header names it.Create, Update, Actions, UploadLeave out X-Idempotency-Key on a write.Available
400password_protected_fileBAD_REQUEST_ERROR
business
document_upload
The file is password protected.UploadA password-protected PDF.Available
400step_not_dueBAD_REQUEST_ERROR
business
validation
The value or action is not due, yet or at all, such as a bank account before the business type. metadata.due lists what is due. Send only what the requirements list to avoid it.Update, ActionsA bank account before the business type.Available
400idempotency_key_reusedBAD_REQUEST_ERROR
business
null
This X-Idempotency-Key was used in the last 24 h with a different body or file. Send a new key for a different request.Create, Update, Actions, UploadThe same key with a different body.Available
401invalid_credentialsBAD_REQUEST_ERROR
business
authentication
The Authorization header is missing or is not Basic, or the key is not a partner key. It also fires when the secret is wrong, was revoked or is past its rotation window.Create, List, Fetch, Update, Actions, Upload, List documents, Fetch document, Delete documentA wrong secret.Available
403consent_withdrawnBAD_REQUEST_ERROR
business
authentication
The sub-merchant withdrew, through Razorpay, the platform’s permission to act on the account. The call never succeeds again for this platform.Fetch, Update, Actions, Upload, List documents, Fetch document, Delete documentAny call after settlement account 000000000007 withdraws access.Available
403ip_not_allowedBAD_REQUEST_ERROR
business
authentication
A request came from an Internet Protocol (IP) address outside the app’s allowlist for its mode. Test mode checks it once the test-mode allowlist has an entry.Create, List, Fetch, Update, Actions, Upload, List documents, Fetch document, Delete documentA call from outside your app’s test-mode allowlist.Available
403onboarding_not_enabledBAD_REQUEST_ERROR
business
authentication
The app does not have the Onboarding APIs turned on in this mode, or Razorpay turned them off.Create, List, Fetch, Update, Actions, Upload, List documents, Fetch document, Delete documentA test key pair from an app whose Onboarding APIs are off for test mode on the Partner Dashboard.Available
404not_foundBAD_REQUEST_ERROR
business
null
The resource does not exist, or the account is not mapped to the platform’s app in this mode. Both look the same, so an ID cannot reveal who banks with Razorpay. field names the ID.Fetch, Update, Actions, Upload, List documents, Fetch document, Delete documentacc_DoesNotExist01, or a deleted file_ ID.Available
409field_lockedBAD_REQUEST_ERROR
business
null
The value cannot change in the product’s current status. field names it, and metadata.status is the status that locks it.UpdateA new bank account while edd_pending.Available
409idempotency_in_progressBAD_REQUEST_ERROR
business
null
A request with this X-Idempotency-Key is still running. Retry after Retry-After. The result is not stored until it finishes.Create, Update, Actions, UploadThe same key sent twice at once.Available
413file_too_largeBAD_REQUEST_ERROR
business
document_upload
The file is larger than 20 MB. metadata.max_bytes is the limit.UploadA 21 MB file.Available
415unsupported_media_typeBAD_REQUEST_ERROR
business
document_upload
The file is not a PDF, JPEG or PNG, read from its bytes. metadata.detected_type is what was found.UploadA .heic file.Available
429rate_limitedBAD_REQUEST_ERROR
business
null
The app sent more requests than its rate limit. Retry after Retry-After.Create, List, Fetch, Update, Actions, Upload, List documents, Fetch document, Delete document6 sends of one action in an hour. Your app’s overall limit is live only.Available
500internal_errorSERVER_ERROR
internal
null
A problem inside Razorpay. Retry the call. A write retried with the same X-Idempotency-Key does not act twice.Create, List, Fetch, Update, Actions, Upload, List documents, Fetch document, Delete documentNone. A server error cannot be forced in test mode.Live only
503provider_unavailableSERVER_ERROR
verification_provider
ckyc_otp
A registry, bank or SMS or email provider that an action calls did not answer. Nothing ran and the request is fine, so retry after Retry-After. Checks inside an update never fail the call this way.Actionssend_ckyc_otp for PAN ABCPD1234W.Available

2. Failed Checks

A failed check returns 200. The element’s verification.status is rejected, with the code below in verification.error_code. The description below is in verification.error_description, and the requirement comes back due. Branch on the code and show the description, which can change. The last 4 codes are for links, which have no element to carry a code. The action stays due, and you run it again for a new link. The table below lists every failed check code:
verification.error_codeCheckWhenDescriptionWhat is due nextTest valueTest mode
pan_not_foundPANThe PAN registry has no such PAN, or rejected it as invalid.We couldn't find this PAN. Check the number, or upload the PAN card.The PAN again, or the PAN card, as the options of one composite requirement.ABCPD1234KAvailable
pan_name_mismatchPANThe PAN exists, but its holder is not the signatory named for the company.This PAN belongs to someone other than the signatory. Send the signatory's own PAN.The signatory’s name and PAN again.Name Rohan Kulkarni with PAN AANPI2846KAvailable
pan_check_unavailablePANThe PAN registry did not answer, or answered with an error. The PAN itself is fine.We couldn't check this PAN at the moment. Upload the PAN card instead.The PAN card, or the PAN again later.ABCPD1234DAvailable
promoter_underagePANThe PAN holder is under 18.Based on the date of birth linked to this PAN, you must be 18 years or older to register with Razorpay. If you believe this is an error, contact Razorpay support.Nothing the platform sends clears it. The sub-merchant contacts Razorpay.ABCPD1234MAvailable
pan_card_mismatchPAN cardThe PAN printed on the card is not the PAN sent.The PAN on this card doesn't match the PAN you entered. Upload the card for that PAN.The PAN card again.PERSONALPANMISMATCHFRONT.jpgAvailable
pan_card_name_mismatchPAN cardThe name on the card is not the owner’s or signatory’s.The name on this PAN card doesn't match. Upload your own PAN card.The PAN card again.PERSONALPANNAMEMISMATCHFRONT.jpgAvailable
pan_card_name_unreadablePAN cardNo name or number could be read on the card.We couldn't read this PAN card. Upload a clear photo or scan of the front.The PAN card again.PERSONALPANUNREADABLEFRONT.jpgAvailable
not_a_pan_cardPAN cardThe file is not a PAN card.This doesn't look like a PAN card. Upload the front of your PAN card.The PAN card again.WRONGFRONT.jpgAvailable
otp_invalidCentral KYC Records Registry (CKYC) codeThe CKYC code does not match the one sent.The code didn't match. Try again, or request a new code.The corrected code with the same request ID. ckyc_otp and ckyc_request_id stay due.PAN ABCPD1234A, then code 000000Available
otp_expiredCKYC codeThe CKYC code was right but has expired, or a wrong code was tried 3 times.This code has expired. Request a new code.send_ckyc_otp again for a new code. The send action is due again.PAN AICPD1234U, then any code other than 000000Available
ckyc_unavailableCKYCThe CKYC record could not be downloaded, for a system reason.We couldn't fetch your KYC record. Upload a proof of address instead.The proof of address (Aadhaar, passport or voter ID).PAN ABCPD1234X, then any code other than 000000Available
poa_name_mismatchProof of addressThe address proof is not in the person’s name.The name on this document doesn't match. Upload an address proof in your own name.The proof of address again.AADHARMISMATCHFRONT.jpgAvailable
poa_unreadableProof of addressThe address proof could not be read.We couldn't read this document. Upload a clear photo or scan.The proof of address again.AADHAARUNREADABLEFRONT.jpgAvailable
bank_name_mismatchBank accountThe account holder’s name does not match the PAN name or the business name.The account must be in the name of your business. Please use a different account.Another account, or a ₹1 UPI payment from it, as the options of one composite requirement.2100000011Available
bank_details_incorrectBank accountThe account number or Indian Financial System Code (IFSC) is wrong.The account number or IFSC is incorrect. Check the details and try again.The account again, or a ₹1 UPI payment from it.2100000040Available
bank_account_unusableBank accountThe bank reported the account as frozen, blocked, closed or Non-Resident External (NRE).This account cannot receive payments. Please use a different bank account.A different account, or a ₹1 UPI payment from one.1234567892Available
bank_check_unavailableBank accountThe bank could not be reached. The account itself is fine.We could not reach your bank to verify the account. Verify it with a ₹1 UPI payment from the account.The bank_account composite requirement again: the account, or a ₹1 UPI payment from it.2100000039Available
bank_not_verifiedBank accountAny other failure. Razorpay does not say why.We could not verify this account. Check the details and try again.The account again, or a ₹1 UPI payment from it.2100000031Available
gstin_name_mismatchGoods and Services Tax Identification Number (GSTIN)The GSTIN is registered to another business.This GSTIN is registered to a different business. Check the GSTIN, or send your Udyam number instead.The GSTIN again, or the Udyam number.27ABCPD7892C1Z5Available
gstin_not_foundGSTINThe Goods and Services Tax (GST) registry has no such GSTIN, or the GSTIN is cancelled.We couldn't find this GSTIN. Check the number, or send your Udyam number instead.The GSTIN again, or the Udyam number.07AADCB1234M1ZXAvailable
udyam_name_mismatchUdyam numberThe Udyam registration is in another business’s name.This Udyam number is registered to a different business. Check the number, or send your GSTIN instead.The Udyam number again, or the GSTIN.UDYAM-MH-19-0005005Available
udyam_not_foundUdyam numberThe Udyam registry has no such number.We couldn't find this Udyam number. Check the number, or send your GSTIN instead.The Udyam number again, or the GSTIN.UDYAM-MH-19-0004750Available
website_unreachableWebsiteThe website could not be opened, or is not live.We couldn't open your website. Check that it's live, or share another one.The website again.https://www.kc-not-found.comAvailable
link_expiredLinkThe sub-merchant did not complete the step before metadata.expires_at.This link has expired. Run the action again for a new link.The action is due again. Run it for a new link.Expire the link on any hosted test pageAvailable
video_kyc_failedVideo KYCThe agent could not verify the person on the call. Examples are a face that did not match the PAN photo or a dropped call.We couldn't complete your video KYC. Start a new call when you're ready.The action is due again. Run it for a new call.Unable to verify on the video KYC test pageAvailable
digilocker_failedDigiLockerThe sub-merchant declined to share the Aadhaar in DigiLocker, or DigiLocker returned no Aadhaar.We didn't get your Aadhaar from DigiLocker. Try again, or upload a proof of address.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.Decline on the DigiLocker test pageAvailable
upi_payment_failedUPI ₹1 paymentThe ₹1 payment did not come from an account in the business’s or owner’s name, or it failed.We couldn't verify the account from this payment. Pay from an account in your business's name, or share the account details.The action is due again. Run it for a new link, or send the account.Pay from another person’s account on the UPI test pageAvailable

3. Review Reasons

In needs_clarification, each flagged point comes back as a requirement with the reviewer’s own wording in description and the reason in requirement_reason. These are the reasons a reviewer can flag, with the test value that raises each one. The table below lists every review reason:
ReasonRequirementWhenExample descriptionTest valueTest mode
bank_account_ownership_unconfirmedbank_accountThe reviewer could not confirm the business or its owner holds the settlement account.A reviewer couldn't confirm that the payout account is held in your name. Share an account in your name, pay ₹1 from it, or reply.Settlement account 000000000003Available
website_no_productswebsiteThe website does not list products or prices.The website doesn't list any products or prices yet. Share a website with your products and prices, or explain how customers will buy from you.Website https://www.kc-no-products.comAvailable
website_policies_missingwebsiteThe website has no refund, cancellation or contact policy.The website needs refund, cancellation and contact details. Add them, or explain how customers reach you.Website https://www.kc-no-policies.comAvailable
business_proof_unclearproof_of_businessThe registration document is unreadable, expired or in another name.We couldn't confirm your business from this document. Upload a clear, current registration in the business's name.A business proof file named UNCLEAR_ plus the PAN, such as UNCLEAR_AANPI2846K.pdfAvailable
address_proof_unclearproof_of_address_for_individualThe proof of address is unreadable, cropped or in another name.We couldn't read your proof of address. Upload both sides of an Aadhaar, voter ID or passport in your name, or use DigiLocker.An Aadhaar front named AADHAARUNCLEARFRONT.jpgAvailable
category_mismatchNoneWhat the business sells does not match its category.What your business sells doesn't match the category you chose. Pick the category that fits.A Merchant Category Code (MCC) that does not match the website, such as https://curlec.com with MCC 5399Available

4. Composite Requirements

A composite requirement answers one point with its sub_requirements, combined as its fulfillment_criteria says. Under one_of, answer one sub-requirement and the whole composite clears. Under any_of, answer at least one. Under all_of, answer every one. A composite’s requirement_code is one of the codes below. A stakeholder’s requirement carries the same code. Its inputs’ field_path names the stakeholder, such as business_profile.stakeholders.per_V1kr4mSh4hQx2W.documents.aadhaar_front. The table below lists every composite requirement:
CodeDescriptionFulfilment criteriaSub-requirements
ckyc_fetchThe person's CKYC record, fetched with a code or skipped.one_of
  • skip_ckyc: business_profile.authorized_person.identity_numbers.individual_ckyc.is_skipped
  • send_ckyc_otp (action)
individual_panThe person's PAN: the number, or the PAN card.one_of
  • individual_pan_number: business_profile.authorized_person.identity_numbers.individual_pan
  • individual_pan_card: business_profile.authorized_person.documents.individual_pan_document
business_panThe business PAN: the number, or the PAN card.one_of
  • business_pan_number: business_profile.identity_numbers.business_pan
  • business_pan_card: business_profile.documents.business_pan
proof_of_address_for_individualVerify the proof of address for an individual. It can be done through one of the multiple ways.one_of
  • create_aadhaar_digilocker_link (action)
  • poa_via_document_upload (one_of)
    • poa_via_aadhaar_documents (all_of)
      • poa_aadhaar_front: business_profile.authorized_person.documents.aadhaar_front
      • poa_aadhaar_back: business_profile.authorized_person.documents.aadhaar_back
    • poa_via_passport_documents (all_of)
      • poa_passport_front: business_profile.authorized_person.documents.passport_front
      • poa_passport_back: business_profile.authorized_person.documents.passport_back
    • poa_via_voter_id_documents (all_of)
      • poa_voter_id_front: business_profile.authorized_person.documents.voter_id_front
      • poa_voter_id_back: business_profile.authorized_person.documents.voter_id_back
business_identityThe company's identity: the CIN or the certificate of incorporation.
For a private limited, public limited or Section 8 company.
one_of
  • cin: business_profile.identity_numbers.cin
  • certificate_of_incorporation: business_profile.documents.certificate_of_incorporation
proof_of_businessProof that your business exists: one registration document and one registration number.
For a proprietorship.
all_of
  • proof_of_business_document (one_of)
    • gst_certificate: business_profile.documents.gst_certificate
    • udyam_registration_certificate: business_profile.documents.udyam_registration_certificate
    • shop_establishment: business_profile.documents.shop_establishment
  • proof_of_business_number (one_of)
    • gstin: business_profile.identity_numbers.gstin
    • udyam_registration: business_profile.identity_numbers.udyam_registration
bank_accountYour settlement bank account.
Listed only after a failed check or in needs_clarification. clarify_bank_account appears only in needs_clarification. Otherwise the requirement is listed as settlement_bank_account.
one_of
  • settlement_bank_account (all_of)
    • bank_account_number: bank_accounts.settlements_primary.account_number
    • bank_routing_code: bank_accounts.settlements_primary.routing_code
    • bank_routing_code_type: bank_accounts.settlements_primary.routing_code_type
  • create_upi_link (action)
  • clarify_bank_account: products.payment_gateway.clarification_responses.bank_accounts.settlements_primary
settlement_bank_accountThe bank account that receives settlements, in the name on your PAN.all_of
  • bank_account_number: bank_accounts.settlements_primary.account_number
  • bank_routing_code: bank_accounts.settlements_primary.routing_code
  • bank_routing_code_type: bank_accounts.settlements_primary.routing_code_type
websiteYour website.
Listed only in needs_clarification. Otherwise the requirement is listed as website_url.
one_of
  • website_url: products.payment_gateway.payment_channels.website.primary
  • clarify_website: products.payment_gateway.clarification_responses.products.payment_gateway.payment_channels.website.primary
payment_channelsWhere you take payments: a website, an Android app or an iOS app. Any one is enough.
Optional. Any one channel answers it.
one_of
  • website_url: products.payment_gateway.payment_channels.website.primary
  • app_android_url: products.payment_gateway.payment_channels.app_android.url
  • app_ios_url: products.payment_gateway.payment_channels.app_ios.url
accept_terms_of_serviceShow the sub-merchant Razorpay's terms of service and record their acceptance.
Sending it submits the product.
all_of
  • acceptance_ip: products.payment_gateway.terms_of_service_acceptance.ip
  • acceptance_device_fingerprint_id: products.payment_gateway.terms_of_service_acceptance.device_fingerprint_id
business_model_clarificationsAnswer the questions about your business model.
One input per question, coded by the question ID. Its value_type comes from bmc_input_type: single_select becomes enum, multi_select stays multi_select and free_text becomes text. Each input carries the question’s options.
all_of
  • <question_id>: business_profile.business_category.business_model_clarifications.<question_id>.answer
registered_addressYour business's registered address.all_of
  • address_line1: business_profile.addresses[type=registered_address].line1
  • address_line2: business_profile.addresses[type=registered_address].line2
  • address_city: business_profile.addresses[type=registered_address].city
  • address_state: business_profile.addresses[type=registered_address].state
  • address_postal_code: business_profile.addresses[type=registered_address].postal_code
  • address_country: business_profile.addresses[type=registered_address].country
operational_addressThe address your business operates from.all_of
  • address_line1: business_profile.addresses[type=operational_address].line1
  • address_line2: business_profile.addresses[type=operational_address].line2
  • address_city: business_profile.addresses[type=operational_address].city
  • address_state: business_profile.addresses[type=operational_address].state
  • address_postal_code: business_profile.addresses[type=operational_address].postal_code
  • address_country: business_profile.addresses[type=operational_address].country
authorized_personThe authorized person: their name and PAN.all_of
  • authorized_person_name: business_profile.authorized_person.name
  • individual_pan (one_of)
    • individual_pan_number: business_profile.authorized_person.identity_numbers.individual_pan
    • individual_pan_card: business_profile.authorized_person.documents.individual_pan_document
Last modified on November 18, 2026