> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant Risk API Errors

> Errors of the Razorpay Merchant Risk APIs: partner actions, answering risk requirements and uploading documents, with the cause of each and the fix.

Available in🇮🇳 India

The Merchant Risk APIs use the error object and the HTTP status codes of the Accounts API:

* `2xx`: Success
* `4xx`: A problem with the request or the account's state
* `5xx`: A problem on Razorpay's side

Repeating the current state with a partner action is not an error. It returns `200` and changes nothing.

## Error Object

Every error response carries the same envelope with 7 fields. Branch on `reason` 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.

```json Failure theme={null}
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "This field can't be changed.",
    "source": "business",
    "step": "validation",
    "reason": "field_read_only",
    "field": "status_reason.requirement_id",
    "metadata": {}
  }
}
```

## Partner Action Errors

These errors are specific to [partner actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md). Razorpay can add new reasons. Handle an unknown reason by its HTTP status.

> [accordion] This field can't be changed.
>
> **Code:** `400`
>
> **Reason:** `field_read_only`
>
> The 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:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Send only `status_reason.code` and `status_reason.description`. `error.field` names the read-only field.

> [accordion] Razorpay disabled payment acceptance. Only Razorpay can enable it.
>
> **Code:** `400`
>
> **Reason:** `payments_disable_not_reversible`
>
> You called `enable_payments` while `payment_acceptance.initiated_by` is `razorpay`.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Show the sub-merchant `status_reason.description`. If `status_reason.requirement_id` is set, answer that requirement. `metadata.requirement_id` repeats it.

> [accordion] Razorpay put settlement on hold. Only Razorpay can release it.
>
> **Code:** `400`
>
> **Reason:** `settlement_disable_not_reversible`
>
> You called `enable_settlement` while `settlement.initiated_by` is `razorpay`.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Show the sub-merchant `status_reason.description`. If `status_reason.requirement_id` is set, answer that requirement. `metadata.requirement_id` repeats it.

> [accordion] Razorpay suspended the product. Only Razorpay can unsuspend it.
>
> **Code:** `400`
>
> **Reason:** `suspension_not_reversible`
>
> You called `unsuspend` on a product that Razorpay suspended.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Show the sub-merchant `status_reason.description` from either object. Answer the requirement in `status_reason.requirement_id`, if any.

> [accordion] The product is suspended. Reverse the suspension first.
>
> **Code:** `400`
>
> **Reason:** `product_suspended`
>
> You called `disable_payments`, `enable_payments`, `disable_settlement` or `enable_settlement` while the product's `status` is `suspended`.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Reverse the suspension first if you set it, with `unsuspend`. A suspension by Razorpay can only be reversed by Razorpay.

> [accordion] Partner actions aren't enabled for this platform.
>
> **Code:** `403`
>
> **Reason:** `partner_actions_not_enabled`
>
> You 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:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Contact Razorpay to switch on partner actions for your platform.

## Partner Action Request Errors

These follow the Accounts API actions conventions.

> [accordion] The account ID isn't valid.
>
> **Code:** `400`
>
> **Reason:** `invalid_account_id`
>
> The account ID in the path is not `acc_` followed by 14 letters or digits.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Send the account ID as `acc_` followed by 14 letters or digits, such as `acc_Rk9Xm2Qp7Zt4Nb`.

> [accordion] The idempotency key isn't valid.
>
> **Code:** `400`
>
> **Reason:** `invalid_format`
>
> `X-Idempotency-Key` is not 16-64 printable ASCII characters.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Send `X-Idempotency-Key` with 16-64 printable ASCII characters.

> [accordion] Choose one of the allowed values (action).
>
> **Code:** `400`
>
> **Reason:** `invalid_option`
>
> `action` is not one of the supported actions. `metadata.allowed_values` lists the values.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Send an `action` from `metadata.allowed_values`.

> [accordion] This idempotency key was already used with a different request.
>
> **Code:** `400`
>
> **Reason:** `idempotency_key_reused`
>
> You sent this `X-Idempotency-Key` before with a different action or different inputs.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
>
> **Solution:** Send a new `X-Idempotency-Key` for a different request. Reuse a key only to retry the same request.

## Fetch a Requirement Errors

> [accordion] The requirement doesn't exist on this account.
>
> **Code:** `404`
>
> **Reason:** `requirement_not_found`
>
> No requirement with this `requirement_id` is on the account's `payment_gateway` product.
>
> **Returned by:**
>
> * [Fetch a Requirement](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#fetch-a-requirement)
>
> **Solution:** Check the ID in `error.field`. Use the `id` of a requirement on this account.

## Upload Errors

> [accordion] The request is missing a required field.
>
> **Code:** `400`
>
> **Reason:** `invalid_request`
>
> The request has one of these problems:
>
> * The body is not `multipart/form-data`.
> * `file` or `document_type` is missing.
> * The request has more than 1 file.
> * `document_type` in the body is not the one in the path.
>
> **Returned by:**
>
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Send a `multipart/form-data` body with 1 `file` and the same `document_type` as the path.

> [accordion] Choose one of the allowed values (document type).
>
> **Code:** `400`
>
> **Reason:** `invalid_option`
>
> `document_type` is not a document type.
>
> **Returned by:**
>
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Send the requirement's `requirement_code`, or another valid document type.

> [accordion] The file can't be read. Upload it again.
>
> **Code:** `400`
>
> **Reason:** `invalid_file`
>
> Razorpay cannot read the file. For example, the PDF is truncated or corrupt.
>
> **Returned by:**
>
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Check that the file is complete and readable, then upload it again.

> [accordion] Upload the file without a password.
>
> **Code:** `400`
>
> **Reason:** `password_protected_file`
>
> The file is password protected.
>
> **Returned by:**
>
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Remove the password from the file, then upload it again.

> [accordion] The file is too large.
>
> **Code:** `413`
>
> **Reason:** `file_too_large`
>
> The file is larger than 20 MB.
>
> **Returned by:**
>
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Compress or split the file to 20 MB or less, then upload it again.

> [accordion] Upload a PDF, JPEG or PNG file.
>
> **Code:** `415`
>
> **Reason:** `unsupported_media_type`
>
> The file is not a PDF, JPEG or PNG. `metadata.detected_type` names the type Razorpay found.
>
> **Returned by:**
>
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **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.

> [accordion] A required header is missing.
>
> **Code:** `400`
>
> **Reason:** `missing_header`
>
> `X-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:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Send `X-Idempotency-Key` with 16-64 printable ASCII characters.

> [accordion] This request conflicts with an earlier one.
>
> **Code:** `409`
>
> **Reason:** `idempotency_key_mismatch`
>
> You used this `X-Idempotency-Key` in the last 24 h with a different body or file.
>
> **Returned by:**
>
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Send a new `X-Idempotency-Key` for a different request. Reuse a key only to retry the same request.

> [accordion] The earlier request is still being processed.
>
> **Code:** `409`
>
> **Reason:** `idempotency_in_progress`
>
> A request with this `X-Idempotency-Key` is still running. Razorpay stores its result only when it finishes.
>
> **Returned by:**
>
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Wait for the time in the `Retry-After` header, then retry with the same key.

## Common Errors

Every endpoint returns these errors.

> [accordion] The credentials aren't valid.
>
> **Code:** `401`
>
> **Reason:** `invalid_credentials`
>
> The `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:**
>
> * [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Send your partner key and secret as HTTP Basic credentials. Check that the secret is current for the key.

> [accordion] Onboarding isn't enabled for this platform.
>
> **Code:** `403`
>
> **Reason:** `onboarding_not_enabled`
>
> Your app does not have access to the Onboarding APIs in this mode. Razorpay may also have turned off your app's access.
>
> **Returned by:**
>
> * [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Contact Razorpay to get access to the Onboarding APIs for your app in this mode.

> [accordion] Requests from this address aren't allowed.
>
> **Code:** `403`
>
> **Reason:** `ip_not_allowed`
>
> The 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:**
>
> * [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Send requests from an IP range on your app's allowlist for this mode.

> [accordion] These credentials can't perform this operation.
>
> **Code:** `403`
>
> **Reason:** `insufficient_scope`
>
> Your 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:**
>
> * [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Use a key and secret pair with a scope listed in `metadata.required_scopes`.

> [accordion] The business has withdrawn this platform's access to its Razorpay account.
>
> **Code:** `403`
>
> **Reason:** `consent_withdrawn`
>
> Through 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 an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Stop calling this account and update your records.

> [accordion] The requested resource doesn't exist.
>
> **Code:** `404`
>
> **Reason:** `not_found`
>
> No 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:**
>
> * [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Check the ID in `error.field`. Use the ID of an account mapped to your app, in the same mode as your key.

> [accordion] Too many requests. Try again shortly.
>
> **Code:** `429`
>
> **Reason:** `rate_limited`
>
> Your app sent more requests than its rate limit allows.
>
> **Returned by:**
>
> * [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Wait for the time in the `Retry-After` header, then retry.

> [accordion] Something went wrong on our side. Try again.
>
> **Code:** `500`
>
> **Reason:** `internal_error`
>
> Something went wrong inside Razorpay.
>
> **Returned by:**
>
> * [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md)
> * [Partner Actions](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md)
> * [Answer Requirements](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#answer-requirements)
> * [Upload a Document](https://razorpay.com/docs/api/partners/accounts/merchant-risk/clarifications.md#upload-a-document)
>
> **Solution:** Retry the request. A write retried with the same `X-Idempotency-Key` does not act twice.
