Errors and resource limits
Handle transport policy errors separately from JSON-RPC method errors. A method supported by a local node may still be denied by a gateway allowlist or observer policy.
| JSON-RPC code | Typical meaning | Client action |
|---|---|---|
-32700 | Invalid JSON | Correct encoding |
-32600 | Invalid request/envelope | Correct JSON-RPC fields and bounds |
-32601 | Method not found | Check the supported profile |
-32602 | Invalid parameters/context | Correct canonical fields, range and hash |
-32603 | Internal state/backend failure | Stop retrying writes; operator recovery may be required |
-32000 | Execution/admission/native work failure | Inspect message and current state |
-32005 | Ethereum RPC resource budget | Split query/batch or reduce work |
3 | Simulated EVM revert | Decode revert data; fix the call |
Common transaction messages include invalid chain id, nonce too low, insufficient funds for gas * price + value, replacement transaction underpriced, sender not an eoa, and txpool is full. The pool refuses a transaction whose gas limit is above 1,000,000 with exceeds block gas limit; other gas messages include transaction gas limit too high (above 16,777,216), intrinsic gas too low and insufficient gas for floor data gas cost. A hex parameter with a doubled 0x0x prefix is rejected with -32602.
Local profile limits
| Boundary | Inspected development limit |
|---|---|
| JSON input body | 512 KiB |
| JSON nesting | 32 levels |
| Local JSON-RPC batch | 16 requests, sequential and non-atomic |
| Public development gateway | One object; batches refused |
| Per-envelope Ethereum state reads | 4, shared with native proof reads |
| Per-envelope simulated executions | 32 |
| Ethereum uncached block loads | 1,024 |
| Transaction admission gas limit | 1,000,000 per transaction |
| Ethereum log query | 1,024 blocks; 10,000 logs or 960 KiB |
| Block receipts | 960 KiB |
| Local HTTP/WebSocket response | 1 MiB; method result caps sit below it |
| Native RPC session | Up to 8 subscriptions; 64 events / 64 KiB live queue |
| Local WebSocket transport | 512 KiB messages; cumulative work/output bounds and deadline |
Method-level caps do not override transport caps. A large method result may fail at a smaller HTTP or WebSocket boundary; query smaller ranges/pages. Gateway per-client budgets can be stricter. Values are development defaults, not testnet/mainnet SLAs.
Transport and recovery
Local requests need the expected loopback Host, POST / and JSON content type. Web-page Origins receive 403. A gateway requires a bearer credential; source/client rate limits can yield 429 or close a connection.
After a disconnect, resubscribe and backfill from a durable cursor. After an ambiguous submission, query the known hash before constructing another operation. Never interpret a network timeout as proof that a transaction did not commit.