> ## 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.

# 9. Error Codes

> Know about the Onboarding APIs error codes and how to handle them.

Available in
🇮🇳 India

Every non-`2xx` response from the Onboarding APIs carries the same error envelope. Branch your handling on `error.reason`, the stable machine-readable field. Show `error.description` to the sub-merchant.

```json Error theme={null}
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "The PAN must be 10 characters: 5 letters, 4 digits and a letter.",
    "source": "business",
    "step": "validation",
    "reason": "invalid_format",
    "field": "business_profile.authorized_person.identity_numbers.individual_pan",
    "metadata": {
      "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$"
    }
  }
}
```

> [!NOTE]
>
> **Handy Tips**
>
> A failed verification check is not an error. It returns `200`, with the code in the element's `verification.error_code`. Know more about [failed-check codes](https://razorpay.com/docs/partners/aggregators/onboarding-api/collect-requirements.md#2-3-failed-check-codes).

## Error Fields

The table below lists the fields of the `error` object:

| Field | Description |
| - | - |
| `code` | The error class: `BAD_REQUEST_ERROR` or `SERVER_ERROR`. |
| `description` | A sentence to show the sub-merchant. It never repeats a value you sent, or anything Razorpay holds about the business. |
| `source` | Where the error came from: `business`, `verification_provider` or `internal`. |
| `step` | The onboarding step, such as `validation`, `document_upload` or `ckyc_otp`. Can be `null`. |
| `reason` | A stable, machine-readable reason, such as `invalid_format`. |
| `field` | The request field or account path the error is about. Can be `null`. |
| `metadata` | Structured hints, such as `allowed_values` on `invalid_option`. `{}` when it has nothing to add. |

## Error Classes

The table below lists the error classes and their sources:

| `code` | `source` | What It Means | What You Do |
| - | - | - | - |
| `BAD_REQUEST_ERROR` | `business` | The request or the sub-merchant's data is wrong, such as a missing field or a bad format. | Fix the request, or ask the sub-merchant to correct the value. Retrying unchanged fails the same way. |
| `SERVER_ERROR` | `verification_provider` | A registry or bank Razorpay calls did not answer. Nothing is wrong with the data. | Retry later. |
| `SERVER_ERROR` | `internal` | A problem inside Razorpay. | Retry. A write retried with the same `X-Idempotency-Key` does not act twice. |

## Reasons by HTTP Status

The table below lists the reasons each HTTP status carries:

| HTTP Status | Reasons | What You Do |
| - | - | - |
| `400` | `invalid_request`, `invalid_format`, `invalid_option`, `missing_header`, `step_not_due`, `invalid_document_url`, `invalid_file`, `invalid_file_name`, `file_name_too_long`, `password_protected_file`, `idempotency_key_reused` | Fix the value that `error.field` names. Use `metadata`, such as `pattern`, `allowed_values` or `due`, for what is expected. |
| `401` | `invalid_credentials` | Check the key and secret. A revoked secret, or one whose rotation window ended, fails here. |
| `403` | `onboarding_not_enabled`, `ip_not_allowed`, `consent_withdrawn` | Check that your app is set up for the mode and the source IP is allowlisted. After `consent_withdrawn`, stop acting on the account. |
| `404` | `not_found` | Check the ID. An account not mapped to your app in this mode looks the same as one that does not exist. |
| `409` | `field_locked`, `idempotency_in_progress` | Do not retry unchanged. For `idempotency_in_progress`, retry after `Retry-After`. |
| `413` | `file_too_large` | Upload a file of 20 MB or less. |
| `415` | `unsupported_media_type` | Upload a PDF, JPEG or PNG file. |
| `429` | `rate_limited` | Retry after `Retry-After`. |
| `500` | `internal_error` | Retry with the same `X-Idempotency-Key`. |
| `503` | `provider_unavailable` | Retry after `Retry-After`. Nothing ran. |

> [!WARNING]
>
> **Watch Out!**
>
> Razorpay can add new reasons. Handle an unknown `reason` by its HTTP status.

Refer to the [Errors](https://razorpay.com/docs/api/partners/accounts/errors.md) reference for every reason, when it occurs and its sample description.
