RPC Error Reference

Conduit RPC responses follow the JSON-RPC 2.0 specification. Errors are returned in two places:

• HTTP layer: the response status code signals the category of failure.
• JSON body: the error object carries a code and message when the request could not be fulfilled.

Most JSON-RPC errors are returned with HTTP 200. Exceptions are noted in the tables below.

HTTP status codes

JSON-RPC error codes

Standard codes

These follow the JSON-RPC 2.0 spec and are returned as HTTP 200 with an error body.

Conduit-specific codes

These are in the -32000 to -32408 range (server-defined per the spec) and may be returned alongside a non-200 HTTP code.

API key errors

All API key errors return HTTP 403 with JSON-RPC code -32403. The message field distinguishes the cause.

Example response (disabled key):

1
{
2
  "jsonrpc": "2.0",
3
  "error": {
4
    "code": -32403,
5
    "message": "disabled rpc key. visit https://app.conduit.xyz/rpc-keys to create a new key"
6
  },
7
  "id": 1
8
}

Rate limit errors (429)

Exceeding your plan’s CU/s throughput limit returns HTTP 429 with JSON-RPC code -32017.

1
{
2
  "jsonrpc": "2.0",
3
  "error": {
4
    "code": -32017,
5
    "message": "Rate limit exceeded. Please get an API key at https://app.conduit.xyz/nodes to increase your rate limit."
6
  },
7
  "id": 1
8
}

Throughput limits by plan:

See Throughput for full guidance on handling 429s, including backoff strategies and how to use batch requests to reduce overhead.

eth_getLogs errors

Conduit enforces two separate limits on eth_getLogs. They produce different errors.

Block range exceeded (from rpcproxy):

1
{
2
  "jsonrpc": "2.0",
3
  "error": {
4
    "code": -32602,
5
    "message": "Log response size exceeded. You can make eth_getLogs requests with up to a 2K block range."
6
  },
7
  "id": 1
8
}

Log count exceeded (from the node backend):

1
{
2
  "jsonrpc": "2.0",
3
  "error": {
4
    "code": -32005,
5
    "message": "logs count limit exceeded (10000) consider refine/narrow down your query"
6
  },
7
  "id": 0
8
}

Fix: paginate your query in chunks of ≤2,000 blocks and filter by topics or address to keep event counts below 10,000. See Throughput for full pagination guidance.

Supported and restricted methods

Conduit supports the full eth_*, net_*, and web3_* standard method suites. A subset of debug_* methods is available on an allowlist. Any method not on the list returns -32001 (HTTP 403).

Allowed debug_* methods:

debug_getExecutionWitness, debug_getRawBlock, debug_getRawHeader, debug_getRawTransaction, debug_getRawReceipts, debug_getBadBlocks, debug_storageRangeAt, debug_getTrieFlushInterval, debug_traceBlock, debug_traceBlockByHash, debug_traceBlockByNumber, debug_traceCall, debug_traceTransaction, debug_dbGet, debug_chainConfig

All trace_* methods are supported. See Compute Units for CU costs.

Batch requests

Conduit accepts JSON-RPC batch requests (an array of request objects in a single HTTP call). The maximum payload size is 5 MB. Exceeding this returns -32014 (HTTP 400).

Retrying errors