2xx: Success4xx: A problem with the request or the sub-merchant’s data5xx: A problem on Razorpay’s side
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 onreason, show description to the sub-merchant and use field to point at the value. Errors never repeat a value you sent.
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.
metadata. field names the value instead.business: Your request or the sub-merchant’s data: a missing field or a bad format, such asreason: invalid_formatatstep: 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 returns503withprovider_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 itsverificationshowsrejectedwith a code such aspan_check_unavailable.internal: A problem inside Razorpay (reason: internal_error). Retry. A write retried with the sameX-Idempotency-Keydoes not act twice.
validation (the request’s own checks), document_upload or ckyc_otp.API Errors
Razorpay can add new reasons. Handle an unknown reason by its HTTP status.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 valid JSON.
- A required field is missing.
- A key is not one the endpoint takes, such as a misspelled or read-only field.
The value isn't in the right format.
The value isn't in the right format.
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_idthat is notfile_followed by 14 letters or digits - An
X-Idempotency-Keythat is not 16-64 printable ASCII characters
- Create an Account
- Fetch Accounts
- Update an Account
- Run an Action
- Upload a Document
- Fetch One Document
- Delete a Document
error.field and send it again. metadata.pattern shows the expected format. metadata.minimum and metadata.maximum show the range.Choose one of the allowed values.
Choose one of the allowed values.
400Reason: invalid_optionA value is not one of the allowed options.Returned by:- Create an Account
- Fetch Accounts
- Update an Account
- Run an Action
- Upload a Document
- Fetch All Documents
metadata.allowed_values lists them when the list is short.A required header is missing.
A required header is missing.
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.This detail isn't needed yet.
This detail isn't needed yet.
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.The document couldn't be downloaded from the link.
The document couldn't be downloaded from the link.
400Reason: invalid_document_urlA document url has one of these problems:- It is not https.
- It points at, or redirects to, a private, loopback or cloud-metadata address.
- Razorpay could not download it.
- The file fails the upload checks.
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.The file name isn't allowed.
The file name isn't allowed.
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.The file name is too long.
The file name is too long.
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.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.This request conflicts with an earlier one.
This request conflicts with an earlier one.
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.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 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.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: Every endpoint.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: 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.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:- Fetch Accounts
- Update an Account
- Run an Action
- Upload a Document
- Fetch All Documents
- Fetch One Document
- Delete a Document
The requested resource doesn't exist.
The requested resource doesn't exist.
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:- Fetch Accounts
- Update an Account
- Run an Action
- Upload a Document
- Fetch All Documents
- Fetch One Document
- Delete a Document
error.field. Use the ID of an account or document of your app, in the same mode as your key.This detail can't be changed at this stage.
This detail can't be changed at this stage.
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.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.The file is too large.
The file is too large.
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.The file format is not accepted for this document type.
The file format is not accepted for this document type.
415Reason: unsupported_media_typeThe request has one of these problems:- The upload body is not
multipart/form-data.error.fieldisContent-Type. - The file format is not accepted for its document type. Razorpay detects the format from the file content, not its name.
error.fieldisfile.
multipart/form-data. Upload the file in a format listed in metadata.accept. metadata.detected_type shows the format found.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: Every endpoint.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: Every endpoint.Solution: Retry the request. A write retried with the same X-Idempotency-Key does not act twice.The verification service is busy. Try again in a few minutes.
The verification service is busy. Try again in a few minutes.
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’sverification.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_failedandupi_payment_failedhave 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_otporemail_otpstays due. An expired code or 3 wrong tries bring backsend_phone_otporsend_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.
We couldn't find this PAN. Check the number, or upload the PAN card.
We couldn't find this PAN. Check the number, or upload the PAN card.
pan_not_foundCheck: PANThe PAN registry has no such PAN or rejected it as invalid.Fields:business_profile.authorized_person.identity_numbers.individual_panbusiness_profile.identity_numbers.business_panbusiness_profile.stakeholders.<stakeholder_id>.identity_numbers.individual_pan
This PAN belongs to someone other than the signatory. Send the signatory's own PAN.
This PAN belongs to someone other than the signatory. Send the signatory's own PAN.
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
We couldn't check this PAN at the moment. Upload the PAN card instead.
We couldn't check this PAN at the moment. Upload the PAN card instead.
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_panbusiness_profile.identity_numbers.business_pan
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.
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.
promoter_underageCheck: PANThe PAN holder is under 18.Fields:business_profile.authorized_person.identity_numbers.individual_panbusiness_profile.authorized_person.documents.individual_pan_document
The PAN on this card doesn't match the PAN you entered. Upload the card for that PAN.
The PAN on this card doesn't match the PAN you entered. Upload the card for that PAN.
pan_card_mismatchCheck: PAN cardThe PAN printed on the card is not the PAN sent.Fields:business_profile.authorized_person.documents.individual_pan_document
The name on this PAN card doesn't match. Upload your own PAN card.
The name on this PAN card doesn't match. Upload your own PAN card.
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
We couldn't read this PAN card. Upload a clear photo or scan of the front.
We couldn't read this PAN card. Upload a clear photo or scan of the front.
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
This doesn't look like a PAN card. Upload the front of your PAN card.
This doesn't look like a PAN card. Upload the front of your PAN card.
not_a_pan_cardCheck: PAN cardThe file is not a PAN card.Fields:business_profile.authorized_person.documents.individual_pan_document
The code didn't match. Try again, or request a new code.
The code didn't match. Try again, or request a new code.
otp_invalidCheck: CKYC codeThe CKYC code does not match the one sent.Fields:business_profile.authorized_person.identity_numbers.individual_ckyc
otp, with the same request_id: ckyc_otp and ckyc_request_id stay due.This code has expired. Request a new code.
This code has expired. Request a new 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
send_ckyc_otp again, for a new code: the send action is due again.We couldn't fetch your KYC record. Upload a proof of address instead.
We couldn't fetch your KYC record. Upload a proof of address instead.
ckyc_unavailableCheck: CKYCRazorpay could not download the CKYC record, for a system reason.Fields:business_profile.authorized_person.identity_numbers.individual_ckyc
The name on this document doesn't match. Upload an address proof in your own name.
The name on this document doesn't match. Upload an address proof in your own name.
poa_name_mismatchCheck: Proof of addressThe address proof is not in the person’s name.Fields:business_profile.authorized_person.documents.aadhaar_frontbusiness_profile.authorized_person.documents.voter_id_frontbusiness_profile.authorized_person.documents.passport_frontbusiness_profile.stakeholders.<stakeholder_id>.documents.aadhaar_frontbusiness_profile.stakeholders.<stakeholder_id>.documents.voter_id_frontbusiness_profile.stakeholders.<stakeholder_id>.documents.passport_front
We couldn't read this document. Upload a clear photo or scan.
We couldn't read this document. Upload a clear photo or scan.
poa_unreadableCheck: Proof of addressRazorpay could not read the address proof.Fields:business_profile.authorized_person.documents.aadhaar_frontbusiness_profile.authorized_person.documents.voter_id_frontbusiness_profile.authorized_person.documents.passport_frontbusiness_profile.stakeholders.<stakeholder_id>.documents.aadhaar_frontbusiness_profile.stakeholders.<stakeholder_id>.documents.voter_id_frontbusiness_profile.stakeholders.<stakeholder_id>.documents.passport_front
The account must be in the name of your business. Please use a different account.
The account must be in the name of your business. Please use a different account.
bank_name_mismatchCheck: Bank accountThe account holder’s name does not match the PAN name or the business name.Fields:bank_accounts.settlements_primary
The account number or IFSC is incorrect. Check the details and try again.
The account number or IFSC is incorrect. Check the details and try again.
bank_details_incorrectCheck: Bank accountThe account number or Indian Financial System Code (IFSC) is wrong.Fields:bank_accounts.settlements_primary
This account cannot receive payments. Please use a different bank account.
This account cannot receive payments. Please use a different bank account.
bank_account_unusableCheck: Bank accountThe bank reported the account frozen, blocked, closed or Non-Resident External (NRE).Fields:bank_accounts.settlements_primary
We could not reach your bank to verify the account. Verify it with a ₹1 UPI payment from the account.
We could not reach your bank to verify the account. Verify it with a ₹1 UPI payment from the account.
bank_check_unavailableCheck: Bank accountRazorpay could not reach the bank. Nothing is wrong with the account.Fields:bank_accounts.settlements_primary
bank_account composite requirement again: the account, or a ₹1 UPI payment from it.We could not verify this account. Check the details and try again.
We could not verify this account. Check the details and try again.
bank_not_verifiedCheck: Bank accountAny other failure. Razorpay does not say why.Fields:bank_accounts.settlements_primary
This GSTIN is registered to a different business. Check the GSTIN, or send your Udyam number instead.
This GSTIN is registered to a different business. Check the GSTIN, or send your Udyam number instead.
gstin_name_mismatchCheck: Goods and Services Tax Identification Number (GSTIN)The GSTIN is registered to another business.Fields:business_profile.identity_numbers.gstin
We couldn't find this GSTIN. Check the number, or send your Udyam number instead.
We couldn't find this GSTIN. Check the number, or send your Udyam number instead.
gstin_not_foundCheck: GSTINThe GST registry has no such GSTIN or the GSTIN is cancelled.Fields:business_profile.identity_numbers.gstin
This Udyam number is registered to a different business. Check the number, or send your GSTIN instead.
This Udyam number is registered to a different business. Check the number, or send your GSTIN instead.
udyam_name_mismatchCheck: Udyam numberThe Udyam registration is in another business’s name.Fields:business_profile.identity_numbers.udyam_registration
We couldn't find this Udyam number. Check the number, or send your GSTIN instead.
We couldn't find this Udyam number. Check the number, or send your GSTIN instead.
udyam_not_foundCheck: Udyam numberThe Udyam registry has no such number.Fields:business_profile.identity_numbers.udyam_registration
This link has expired. Run the action again for a new link.
This link has expired. Run the action again for a new link.
link_expiredCheck: LinkThe sub-merchant did not complete the step before metadata.expires_at.Actions:create_video_kyc_linkcreate_aadhaar_digilocker_linkcreate_upi_link
We couldn't complete your video KYC. Start a new call when you're ready.
We couldn't complete your video KYC. Start a new call when you're ready.
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
We didn't get your Aadhaar from DigiLocker. Try again, or upload a proof of address.
We didn't get your Aadhaar from DigiLocker. Try again, or upload a proof of address.
digilocker_failedCheck: DigiLockerThe sub-merchant declined to share the Aadhaar in DigiLocker or DigiLocker returned no Aadhaar.Actions:create_aadhaar_digilocker_link
Review Reasons
Inneeds_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.
The website needs refund, cancellation and contact details. Add them, or explain how customers reach you.
The website needs refund, cancellation and contact details. Add them, or explain how customers reach you.
website_policies_missingFlagged requirement: websiteThe website has no refund, cancellation or contact policy.Fields:products.payment_gateway.payment_channels.website.primary
We couldn't confirm your business from this document. Upload a clear, current registration in the business's name.
We couldn't confirm your business from this document. Upload a clear, current registration in the business's name.
business_proof_unclearFlagged requirement: proof_of_businessThe registration document is unreadable, expired or in another name.Fields:business_profile.documents.<type>
We couldn't read your proof of address. Upload both sides of an Aadhaar, voter ID or passport in your name, or use DigiLocker.
We couldn't read your proof of address. Upload both sides of an Aadhaar, voter ID or passport in your name, or use DigiLocker.
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>
What your business sells doesn't match the category you chose. Pick the category that fits.
What your business sells doesn't match the category you chose. Pick the category that fits.
category_mismatchFlagged requirement: None. The reviewer flags the business category.What the business sells does not match its category.Fields:business_profile.business_category