Error Codes & Rate Limits

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

Uniblock 429 responses are plan-based rate limits, not generic validation errors. See Rate limits below for how to handle them.

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-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:

{
  "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

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

Rate limits

If you receive a 429 error, your project has reached the request limit included with your current Uniblock plan.

A 429 does not mean Uniblock is down. It means your traffic exceeded your current plan window.

Rate-limit quick reference

Question	Short answer
What triggers `429`?	Request rate above your plan limit
Is this provider-specific?	No, this is Uniblock plan-level
Should I retry?	Yes, with delay/backoff
Do backups bypass `429`?	No, backup routing does not override plan limits
Long-term fix?	Reduce traffic, optimize usage, or upgrade plan

What should I do if I hit a rate limit?

Retry with backoff

Add exponential backoff and jitter before retrying 429 responses.

Reduce request pressure

Lower polling frequency, cache stable data, and batch requests where possible.

Audit traffic patterns

Verify whether release changes, cron jobs, or retries increased request volume.

Scale your plan

If sustained demand exceeds your current allowance, upgrade to a plan with more throughput.

Retry pattern (recommended)

// Exponential backoff with jitter for 429 responses.
async function requestWithBackoff(fn, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
    if (attempt === maxRetries) return res;

    const base = 250 * Math.pow(2, attempt);
    const jitter = Math.floor(Math.random() * 200);
    await new Promise((r) => setTimeout(r, base + jitter));
  }
}

Rate limit FAQ

Are rate limits based on my Uniblock plan?

Yes. Rate limits are based on the limits included with your Uniblock plan.

Does a 429 mean the API is down?

No. A 429 means your project has exceeded its allowed request rate. It does not mean the platform is unavailable.

Will requests start working again?

Yes. Once traffic falls back within your allowed limit window, requests will succeed again.

Can I increase my rate limits?

Yes. If you need more throughput, please upgrade your plan or contact us to discuss a plan that matches your usage.

Should I retry 429 responses?

Yes, but retries should include a short delay or exponential backoff to avoid sending another burst immediately.

Do backup providers avoid 429 errors?

No. Backup providers help with upstream provider failures, but they do not bypass your Uniblock plan limits.

Example 429 response

{
  "error": {
    "code": 429,
    "message": "Too Many Requests"
  }
}

Get Started

Uniblock

Use Cases

Error Codes & Rate Limits

Format

Important behavior for JSON-RPC

Success and fallback codes

Request validation codes

Response processing codes

Common examples

Invalid REST parameter

Invalid JSON-RPC body

Provider response could not be normalized

How to troubleshoot

Rate limits

Rate-limit quick reference

What should I do if I hit a rate limit?

Retry pattern (recommended)

Rate limit FAQ

Are rate limits based on my Uniblock plan?

Does a 429 mean the API is down?

Will requests start working again?

Can I increase my rate limits?

Should I retry 429 responses?

Do backup providers avoid 429 errors?

Example 429 response

​Format

​Important behavior for JSON-RPC

​Success and fallback codes

​Request validation codes

​Response processing codes

​Common examples

​Invalid REST parameter

​Invalid JSON-RPC body

​Provider response could not be normalized

​How to troubleshoot

​Rate limits

​Rate-limit quick reference

​What should I do if I hit a rate limit?

​Retry pattern (recommended)

​Rate limit FAQ

​Are rate limits based on my Uniblock plan?

​Does a 429 mean the API is down?

​Will requests start working again?

​Can I increase my rate limits?

​Should I retry 429 responses?

​Do backup providers avoid 429 errors?

​Example 429 response

​Related guides

Format

Important behavior for JSON-RPC

Success and fallback codes

Request validation codes

Response processing codes

Common examples

Invalid REST parameter

Invalid JSON-RPC body

Provider response could not be normalized

How to troubleshoot

Rate limits

Rate-limit quick reference

What should I do if I hit a rate limit?

Retry pattern (recommended)

Rate limit FAQ

Are rate limits based on my Uniblock plan?

Does a 429 mean the API is down?

Will requests start working again?

Can I increase my rate limits?

Should I retry 429 responses?

Do backup providers avoid 429 errors?

Example 429 response

Related guides