RPC Error Codes

All RPC endpoints return errors as JSON-RPC 2.0 compliant responses with HTTP 200 status. Error details are in the response body.

Error Codes

Standard JSON-RPC 2.0

Defined in the JSON-RPC 2.0 specification.

Code	Message	Description	When Used
-32600	Invalid Request	Malformed JSON-RPC request	Request doesn't match JSON-RPC format, or a batch exceeds the max size (1000 requests per HTTP request)
-32601	Method not found	Method does not exist	Method is unknown to the proxy (typos, methods not supported by Prividium) or reported as `unimplemented` by the upstream sequencer.
-32602	Invalid params	Invalid method parameters	Method called with wrong parameters
-32603	Internal error	Unhandled server error	Unexpected error in request processing

Custom Prividium Codes

These are implementation-specific codes for authentication/authorization, not part of JSON-RPC 2.0 spec.

Code	Message	Description	HTTP Equivalent	When Used
-32090	Unauthorized	User not authenticated	401	Missing or invalid auth token
-32001	Forbidden	User not authorized	403	Valid auth but insufficient permissions

Note: Custom codes use the implementation-defined range.

Examples:

Calling an unknown / unregistered method:

--> {"jsonrpc": "2.0", "method": "eth_doesNotExist", "params": [], "id": 1}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method eth_doesNotExist not found"}, "id": 1}

RPC call without authentication:

--> {"jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"], "id": 1}
<-- {"jsonrpc": "2.0", "error": {"code": -32090, "message": "Unauthorized"}, "id": 1}

RPC call with valid auth but insufficient permissions:

--> {"jsonrpc": "2.0", "method": "eth_sendTransaction", "params": [{"from": "0x...", "to": "0x..."}], "id": 1}
<-- {"jsonrpc": "2.0", "error": {"code": -32001, "message": "Forbidden"}, "id": 1}

For debugging -32090 and -32001 and related authentication issues, see Developer troubleshooting.

Chain-side errors on `eth_sendRawTransaction`

eth_sendRawTransaction is forwarded through the chain's eth_sendRawTransactionSync so authoritative block-build rejections surface as JSON-RPC errors instead of stuck-in-mempool txs. Callers should handle two extra codes on this method in addition to the standard and Prividium auth codes above.

Code	Message	When Used
-32003	`Transaction rejected during execution: …`	The VM rejected the tx at block-build. Includes policy denials (`FilteredByValidator`) and other `InvalidTransaction` variants. The tx will not be mined.
4	EIP-7966 sync timeout	The tx was admitted to the mempool but didn't land in a block within the chain's sync timeout. The tx may still mine; poll `eth_getTransactionReceipt` to confirm.

Examples:

Tx rejected at block-build (e.g. policy denial or insufficient balance after intervening txs):

--> {"jsonrpc": "2.0", "method": "eth_sendRawTransaction", "params": ["0x02f8..."], "id": 1}
<-- {"jsonrpc": "2.0", "error": {"code": -32003, "message": "transaction rejected during execution: FilteredByValidator"}, "id": 1}

Tx admitted but not mined within the sync timeout (caller polls for the receipt):

--> {"jsonrpc": "2.0", "method": "eth_sendRawTransaction", "params": ["0x02f8..."], "id": 1}
<-- {"jsonrpc": "2.0", "error": {"code": 4, "message": "transaction not mined within timeout"}, "id": 1}

HTTP 429 Rate Limit Error

Unlike JSON-RPC errors above, rate limit errors are returned as HTTP responses with status code 429.

HTTP Status	Error Code	Description
429	`RATE_LIMIT_ERROR`	Too many requests within the time window

Response format:

{
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}

Response headers:

Header	Description
`x-ratelimit-limit`	Maximum requests allowed in the current window
`x-ratelimit-remaining`	Requests remaining in the current window
`x-ratelimit-reset`	Unix timestamp when the current window resets
`retry-after`	Seconds to wait before retrying