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. Readerror.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:
| HTTP | error.reason | error.code, error.source and error.step | When | Thrown by | How to trigger in test mode | Test mode |
|---|---|---|---|---|---|---|
400 | file_name_too_long | BAD_REQUEST_ERRORbusinessdocument_upload | The file name is longer than 255 characters. | Upload | A file name of 256 characters. | Available |
400 | invalid_document_url | BAD_REQUEST_ERRORbusinessdocument_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, Update | A document url of https://10.0.0.1/a.pdf. | Available |
400 | invalid_file | BAD_REQUEST_ERRORbusinessdocument_upload | The file cannot be read, such as a truncated or corrupt PDF. | Upload | A truncated PDF. | Available |
400 | invalid_file_name | BAD_REQUEST_ERRORbusinessdocument_upload | The file name has characters that are not allowed, such as a path separator or a control character. | Upload | A file name with /. | Available |
400 | invalid_format | BAD_REQUEST_ERRORbusinessvalidation | 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, Actions | PAN ABC123, a phone without +91 or a code of 5 digits. | Available |
400 | invalid_option | BAD_REQUEST_ERRORbusinessvalidation | 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 documents | business_type: "company", or action send_sms_otp. | Available |
400 | invalid_request | BAD_REQUEST_ERRORbusinessvalidation | 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, Upload | Leave out user when creating an account. Send verification in an update. | Available |
400 | missing_header | BAD_REQUEST_ERRORbusinessvalidation | A required header is missing or malformed. metadata.header names it. | Create, Update, Actions, Upload | Leave out X-Idempotency-Key on a write. | Available |
400 | password_protected_file | BAD_REQUEST_ERRORbusinessdocument_upload | The file is password protected. | Upload | A password-protected PDF. | Available |
400 | step_not_due | BAD_REQUEST_ERRORbusinessvalidation | 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, Actions | A bank account before the business type. | Available |
400 | idempotency_key_reused | BAD_REQUEST_ERRORbusinessnull | 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, Upload | The same key with a different body. | Available |
401 | invalid_credentials | BAD_REQUEST_ERRORbusinessauthentication | 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 document | A wrong secret. | Available |
403 | consent_withdrawn | BAD_REQUEST_ERRORbusinessauthentication | 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 document | Any call after settlement account 000000000007 withdraws access. | Available |
403 | ip_not_allowed | BAD_REQUEST_ERRORbusinessauthentication | 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 document | A call from outside your app’s test-mode allowlist. | Available |
403 | onboarding_not_enabled | BAD_REQUEST_ERRORbusinessauthentication | 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 document | A test key pair from an app whose Onboarding APIs are off for test mode on the Partner Dashboard. | Available |
404 | not_found | BAD_REQUEST_ERRORbusinessnull | 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 document | acc_DoesNotExist01, or a deleted file_ ID. | Available |
409 | field_locked | BAD_REQUEST_ERRORbusinessnull | The value cannot change in the product’s current status. field names it, and metadata.status is the status that locks it. | Update | A new bank account while edd_pending. | Available |
409 | idempotency_in_progress | BAD_REQUEST_ERRORbusinessnull | 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, Upload | The same key sent twice at once. | Available |
413 | file_too_large | BAD_REQUEST_ERRORbusinessdocument_upload | The file is larger than 20 MB. metadata.max_bytes is the limit. | Upload | A 21 MB file. | Available |
415 | unsupported_media_type | BAD_REQUEST_ERRORbusinessdocument_upload | The file is not a PDF, JPEG or PNG, read from its bytes. metadata.detected_type is what was found. | Upload | A .heic file. | Available |
429 | rate_limited | BAD_REQUEST_ERRORbusinessnull | The app sent more requests than its rate limit. Retry after Retry-After. | Create, List, Fetch, Update, Actions, Upload, List documents, Fetch document, Delete document | 6 sends of one action in an hour. Your app’s overall limit is live only. | Available |
500 | internal_error | SERVER_ERRORinternalnull | 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 document | None. A server error cannot be forced in test mode. | Live only |
503 | provider_unavailable | SERVER_ERRORverification_providerckyc_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. | Actions | send_ckyc_otp for PAN ABCPD1234W. | Available |
2. Failed Checks
A failed check returns200. 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_code | Check | When | Description | What is due next | Test value | Test mode |
|---|---|---|---|---|---|---|
pan_not_found | PAN | The 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. | ABCPD1234K | Available |
pan_name_mismatch | PAN | The 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 AANPI2846K | Available |
pan_check_unavailable | PAN | The 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. | ABCPD1234D | Available |
promoter_underage | PAN | The 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. | ABCPD1234M | Available |
pan_card_mismatch | PAN card | The 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.jpg | Available |
pan_card_name_mismatch | PAN card | The 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.jpg | Available |
pan_card_name_unreadable | PAN card | No 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.jpg | Available |
not_a_pan_card | PAN card | The 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.jpg | Available |
otp_invalid | Central KYC Records Registry (CKYC) code | The 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 000000 | Available |
otp_expired | CKYC code | The 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 000000 | Available |
ckyc_unavailable | CKYC | The 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 000000 | Available |
poa_name_mismatch | Proof of address | The 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.jpg | Available |
poa_unreadable | Proof of address | The address proof could not be read. | We couldn't read this document. Upload a clear photo or scan. | The proof of address again. | AADHAARUNREADABLEFRONT.jpg | Available |
bank_name_mismatch | Bank account | The 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. | 2100000011 | Available |
bank_details_incorrect | Bank account | The 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. | 2100000040 | Available |
bank_account_unusable | Bank account | The 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. | 1234567892 | Available |
bank_check_unavailable | Bank account | The 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. | 2100000039 | Available |
bank_not_verified | Bank account | Any 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. | 2100000031 | Available |
gstin_name_mismatch | Goods 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. | 27ABCPD7892C1Z5 | Available |
gstin_not_found | GSTIN | The 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. | 07AADCB1234M1ZX | Available |
udyam_name_mismatch | Udyam number | The 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-0005005 | Available |
udyam_not_found | Udyam number | The 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-0004750 | Available |
website_unreachable | Website | The 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.com | Available |
link_expired | Link | The 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 page | Available |
video_kyc_failed | Video KYC | The 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 page | Available |
digilocker_failed | DigiLocker | The 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 page | Available |
upi_payment_failed | UPI ₹1 payment | The ₹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 page | Available |
3. Review Reasons
Inneeds_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:
| Reason | Requirement | When | Example description | Test value | Test mode |
|---|---|---|---|---|---|
bank_account_ownership_unconfirmed | bank_account | The 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 000000000003 | Available |
website_no_products | website | The 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.com | Available |
website_policies_missing | website | The 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.com | Available |
business_proof_unclear | proof_of_business | The 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.pdf | Available |
address_proof_unclear | proof_of_address_for_individual | The 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.jpg | Available |
category_mismatch | None | What 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 5399 | Available |
4. Composite Requirements
Acomposite 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:
| Code | Description | Fulfilment criteria | Sub-requirements |
|---|---|---|---|
ckyc_fetch | The person's CKYC record, fetched with a code or skipped. | one_of |
|
individual_pan | The person's PAN: the number, or the PAN card. | one_of |
|
business_pan | The business PAN: the number, or the PAN card. | one_of |
|
proof_of_address_for_individual | Verify the proof of address for an individual. It can be done through one of the multiple ways. | one_of |
|
business_identity | The company's identity: the CIN or the certificate of incorporation.For a private limited, public limited or Section 8 company. | one_of |
|
proof_of_business | Proof that your business exists: one registration document and one registration number.For a proprietorship. | all_of |
|
bank_account | Your 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 | The bank account that receives settlements, in the name on your PAN. | all_of |
|
website | Your website.Listed only in needs_clarification. Otherwise the requirement is listed as website_url. | one_of |
|
payment_channels | Where you take payments: a website, an Android app or an iOS app. Any one is enough.Optional. Any one channel answers it. | one_of |
|
accept_terms_of_service | Show the sub-merchant Razorpay's terms of service and record their acceptance.Sending it submits the product. | all_of |
|
business_model_clarifications | Answer 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 |
|
registered_address | Your business's registered address. | all_of |
|
operational_address | The address your business operates from. | all_of |
|
authorized_person | The authorized person: their name and PAN. | all_of |
|