RPC Error Codes

When a request fails, the response body is still valid JSON-RPC: the result field is omitted and the error object contains a numeric code and a message. These codes are distinct from HTTP status codes (e.g. 401, 429, 504). Use the table below to interpret error.code in the response. For a successful HTTP 200, the response may still contain a JSON-RPC error (e.g. chain not supported). Always check for the presence of error in the response body.

Code → meaning and when it occurs

Code	Name	When it occurs
-32700	Parse error	Request body is not valid JSON.
-32600	Invalid request	Malformed JSON-RPC (e.g. missing required fields) or an empty batch.
-32601	Insufficient credits	The API key’s credit balance is too low to serve the request (HTTP 402). Top up in the dashboard and retry.
-32602	Invalid params	Invalid `chainId` in the request path, an `eth_getLogs` block span that exceeds the router limit, a response that is too large, or a block reference that can never resolve (rejected before dispatch).
-32603	Internal error	Router encountered an internal failure. Contact support if persistent.
-32000	Server error	Unspecified server error (fallback when no specific code applies).
-32001	Chain not supported	The given `chainId` has no available nodes or paid plan support.
-32002	Method not supported	The JSON-RPC method is not enabled for this chain.
-32003	Transaction rejected	Passed through from the upstream node (EIP-1474 “Transaction rejected”, e.g. a send that fails validation). The router does not use this code for its own errors — a cooldown is returned as -32005 with HTTP 429.
-32005	Limit exceeded	A throttling limit. Two cases: an `eth_getLogs` query matched too many logs or produced a response too large for the requested block span (HTTP 400), or every node that could serve the route is temporarily in cooldown (HTTP 429, `error.data.reason` = `capacity_cooldown`). See eth_getLogs limits and Cooldowns and rate limiting.
-32007	No block-param nodes	No provider supports the custom block number parameter used in the request (e.g. an `eth_getLogs` query with a specific block range).
-32008	No providers available	No providers are currently available to serve the route.
-32009	All nodes failed	Every provider failed with a non-rate-limit error (HTTP 424). Retry once; if it persists, contact support.
-32011	No opcode-capable nodes	No provider supports the requested opcode at the given block (e.g. an `eth_call` at a historical block), or no provider with verified hypercore state is available for precompile reads.
-32012	Insufficient historical depth	No provider has sufficient historical state depth (or `eth_getLogs` earliest-block support) for the requested block.
-32013	No single provider satisfies all constraints	No single provider supports the full combination of requested constraints (e.g. block range, depth, method). Try reducing the block range or using a more recent block.
-32014	No deep state-read capable nodes	State reads at an explicit historical block may route only to providers that honor historical block tags; no such provider is currently available. Retry at a more recent block.
-32015	No full transaction index	By-hash transaction lookups may route only to providers with a complete transaction index; none is currently available. Very old transactions may be unavailable on some routes.
-32016	No deep-trace-capable providers	Trace methods (`debug_trace`, `trace_`, `arbtrace_*`) route only to providers that retain deep trace history; none is currently available (HTTP 424). Retry later; if it persists, contact support.
-32029	Public rate limited	The public (no-API-key) route’s per-IP rate limit was exceeded (HTTP 429). Sign up for a free account for full access.
-32030	Public capacity exhausted	The public (no-API-key) route’s free-tier capacity is temporarily exhausted. Sign up for a free account for full access.

Standard JSON-RPC codes

-32700 and -32600 follow the JSON-RPC 2.0 spec for parse and invalid request errors.
-32601 is the JSON-RPC 2.0 “Method not found” code, repurposed here to signal an empty credit balance.
-32602 is used for invalid chainId (invalid params) and for eth_getLogs block-span rejections.
-32603 is used for internal router errors.
-32005 follows EIP-1474 (limit exceeded) for both eth_getLogs query-density failures (HTTP 400) and router capacity cooldowns (HTTP 429).
-32xxx in the -32000 range are router-specific and documented above.

eth_getLogs error messages

RouteMesh normalizes upstream eth_getLogs limit errors into two client-facing shapes. Hints appear in error.message (not a separate field):

Code	Base message	When it occurs
-32602	`block range too large`	The requested `fromBlock`/`toBlock` span exceeds the router maximum (10,000 blocks), or upstream rejected the span as too wide.
-32005	`query exceeds max results`	The block span is within limits, but the filter is too dense (too many matching logs or a payload that is too large). Narrow the range or add filter constraints (e.g. `address`, `topics`).

When the router can suggest a smaller span, the message includes a hint suffix:

; try a block range of at most N blocks

Example (-32602, block span too large):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "block range too large; try a block range of at most 10000 blocks"
  }
}

Example (-32005, query too dense):

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32005,
    "message": "query exceeds max results; try a block range of at most 1025 blocks"
  }
}

If no hint is available, the message contains only the base text (no suffix).

What to do when you see an error

-32700 / -32600: Fix the request payload (valid JSON, non-empty batch, required fields present).
-32602: Check the URL path for a valid chainId. For eth_getLogs, reduce toBlock - fromBlock or split the query into smaller chunks. Use the hint suffix when present.
-32003: This code is not returned by the router (it is reserved by EIP-1474 for “Transaction rejected” and may be passed through from an upstream node). If you see it from a provider, treat it as a rejected transaction, not a cooldown.
-32005: Two cases. If the block span is acceptable but the filter returned too much data, narrow fromBlock/toBlock using the hint, or tighten address/topics — see Request behavior: eth_getLogs limits. If the response is HTTP 429 with error.data.reason = capacity_cooldown, every node was temporarily in cooldown: retry after a short backoff — see Request behavior: Cooldowns and rate limiting.
-32014: State reads at an explicit historical block may route only to providers that honor historical block tags. Retry at a more recent block.
-32015: By-hash transaction lookups route only to providers with a complete transaction index. Very old transactions may be unavailable on some routes.
-32016: No provider currently retains the deep trace history needed for the trace method (debug_trace*, trace_*, arbtrace_*). Retry later; if it persists, contact support.
-32001: Use a supported chain or contact us to request support for a new chain.
-32002: The method is not available for this chain; use a different method or chain.
-32603 / -32000: Retry once; if it persists, contact support.

When contacting support, include the X-Batch-Id response header from the failed request if you have it. See Debugging.

Intro

Concepts

Integration

Code → meaning and when it occurs

Standard JSON-RPC codes

eth_getLogs error messages

What to do when you see an error

​Code → meaning and when it occurs

​Standard JSON-RPC codes

​eth_getLogs error messages

​What to do when you see an error

Code → meaning and when it occurs

Standard JSON-RPC codes

eth_getLogs error messages

What to do when you see an error