Skip to main content

​
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 guide. Uniblock 429 responses are plan-based limits, not generic validation errors.

​
Format

Uniblock error codes follow this pattern: 
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-09 Constraint Failure
  • UR-400-10 JSON-RPC Batch Size Exceeded

​
Success and fallback codes

CodeTitleHTTP StatusRetryableMeaning
UR-200-00Request Successful200NoRequest completed successfully.
UR-000-00Unclassified Error500YesFallback code used when an error could not be classified correctly. This usually indicates a classification gap rather than a user input issue.

​
Request validation codes

CodeTitleHTTP StatusRetryableMeaningSuggested action
UR-400-02Invalid Parameter400NoA query or body parameter is invalid.Review your request parameters against the endpoint spec.
UR-400-03Parse Error200NoThe JSON-RPC request body is not valid JSON.Fix JSON syntax issues such as malformed objects, trailing commas, or bad escaping.
UR-400-04Invalid Request200NoThe JSON-RPC request shape or parameters are invalid.Ensure the request follows the JSON-RPC 2.0 format and uses valid params.
UR-400-05Invalid Pagination400NoREST 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-06Invalid Address Format400NoThe blockchain address format is invalid.Validate the address format for the target chain before sending the request.
UR-400-07Invalid Transaction Hash400NoThe transaction hash format is invalid.Send a valid transaction hash for the target chain.
UR-400-08Unsupported Method400NoThe requested JSON-RPC method is not supported or not whitelisted.Use a supported method for the selected network.
UR-400-09Constraint Failure400NoThe request was blocked by validation constraints before reaching a provider.Check the returned error details to see which request constraint failed.
UR-400-10JSON-RPC Batch Size Exceeded200NoThe batch contains more than 1000 JSON-RPC calls.Split large batches into smaller requests.
UR-400-11Forced Test Failure400NoThe request was intentionally failed using the x-force-provider-fail test header.Remove the test header for normal request processing.

​
Response processing codes

These codes mean the provider responded successfully at the HTTP layer, but Uniblock could not safely process the response.
CodeTitleHTTP StatusRetryableMeaningSuggested action
UR-422-01Unprocessable Response422NoThe provider returned a successful response, but the content could not be processed.Retry later or switch providers if the issue persists.
UR-422-02Response Parsing Failed422NoThe provider returned content that could not be parsed as valid JSON.Retry after a short delay.
UR-422-03Response Transformation Failed422NoThe provider response could not be transformed into Uniblock’s expected format.Retry or contact support if it continues.
UR-422-04Response Validation Failed422NoThe 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: 
{
  "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: 
{
  "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: 
{
  "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.