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

# Uniblock Error Codes

> Reference for Uniblock validation and response-processing error codes, including JSON-RPC validation behavior.

# Uniblock Error Codes

This page documents the Uniblock error codes currently defined in the validation catalog. These codes cover:

* Request validation failures
* JSON-RPC request format errors
* Response processing failures
* Success and fallback classification codes

If you receive a `429`, see the dedicated [Rate Limits](/guides/uniblock/rate-limits) guide. Uniblock `429` responses are plan-based limits, not generic validation errors.

## Format

Uniblock error codes follow this pattern:

```text theme={null}
UR-<http-status-family>-<specific-code>
```

Examples:

* `UR-400-02` for an invalid parameter
* `UR-422-01` for an unprocessable provider response
* `UR-200-00` for a successful request classification

## Important behavior for JSON-RPC

Some JSON-RPC validation errors return HTTP `200` with a JSON-RPC error payload instead of an HTTP `4xx` status. In those cases, the Uniblock error code still tells you what went wrong.

This applies to:

* `UR-400-03` Parse Error
* `UR-400-04` Invalid Request
* `UR-400-08` Unsupported Method
* `UR-400-10` JSON-RPC Batch Size Exceeded

## Success and fallback codes

| Code        | Title              | HTTP Status | Retryable | Meaning                         |
| ----------- | ------------------ | ----------- | --------- | ------------------------------- |
| `UR-200-00` | Request Successful | `200`       | No        | Request completed successfully. |

## Request validation codes

| Code        | Title                        | HTTP Status | Retryable | Meaning                                                               | Suggested action                                                                    |
| ----------- | ---------------------------- | ----------- | --------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `UR-400-02` | Invalid Parameter            | `400`       | No        | A query or body parameter is invalid.                                 | Review your request parameters against the endpoint spec.                           |
| `UR-400-03` | Parse Error                  | `200`       | No        | The JSON-RPC request body is not valid JSON.                          | Fix JSON syntax issues such as malformed objects, trailing commas, or bad escaping. |
| `UR-400-04` | Invalid Request              | `200`       | No        | The JSON-RPC request shape or parameters are invalid.                 | Ensure the request follows the JSON-RPC 2.0 format and uses valid params.           |
| `UR-400-05` | Invalid Pagination           | `400`       | No        | REST pagination exceeded the maximum limit or used an invalid cursor. | Keep page size at `1000` or below and verify the cursor is valid.                   |
| `UR-400-06` | Invalid Address Format       | `400`       | No        | The blockchain address format is invalid.                             | Validate the address format for the target chain before sending the request.        |
| `UR-400-07` | Invalid Transaction Hash     | `400`       | No        | The transaction hash format is invalid.                               | Send a valid transaction hash for the target chain.                                 |
| `UR-400-08` | Unsupported Method           | `400`       | No        | The requested JSON-RPC method is not supported or not whitelisted.    | Use a supported method for the selected network.                                    |
| `UR-400-10` | JSON-RPC Batch Size Exceeded | `200`       | No        | The batch contains more than `1000` JSON-RPC calls.                   | Split large batches into smaller requests.                                          |

## Response processing codes

These codes mean the provider responded successfully at the HTTP layer, but Uniblock could not safely process the response.

| Code        | Title                          | HTTP Status | Retryable | Meaning                                                                              | Suggested action                                       |
| ----------- | ------------------------------ | ----------- | --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| `UR-422-01` | Unprocessable Response         | `422`       | No        | The provider returned a successful response, but the content could not be processed. | Retry later or switch providers if the issue persists. |
| `UR-422-02` | Response Parsing Failed        | `422`       | No        | The provider returned content that could not be parsed as valid JSON.                | Retry after a short delay.                             |
| `UR-422-03` | Response Transformation Failed | `422`       | No        | The provider response could not be transformed into Uniblock's expected format.      | Retry or contact support if it continues.              |
| `UR-422-04` | Response Validation Failed     | `422`       | No        | The provider response did not match the expected schema or contained invalid data.   | Retry or use another provider if available.            |

## Common examples

### Invalid REST parameter

If you send an invalid query or body parameter, Uniblock may return:

```json theme={null}
{
  "error": {
    "code": "UR-400-02",
    "title": "Invalid Parameter"
  }
}
```

### Invalid JSON-RPC body

If your JSON-RPC body is malformed, Uniblock may return HTTP `200` with a JSON-RPC error and the matching Uniblock code:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32700,
    "message": "Parse error",
    "uniblockCode": "UR-400-03"
  }
}
```

### Provider response could not be normalized

If an upstream provider responds in an unexpected format, Uniblock may return:

```json theme={null}
{
  "error": {
    "code": "UR-422-03",
    "title": "Response Transformation Failed"
  }
}
```

## How to troubleshoot

1. Identify the Uniblock code returned in the response.
2. Check whether the issue is a request validation problem, a rate limit, or a provider response problem.
3. Fix request formatting issues locally before retrying.
4. If the code is in the `UR-422-*` family and persists, retry later or contact support with the request ID.

## Related guides

* [Rate Limits](/guides/uniblock/rate-limits)
* [Authentication](/guides/uniblock/authentication)
* [API Logs](/guides/uniblock/uniblock-api-logs)