6 minIteradian Engineeringreferencejson-rpc
JSON-RPC 2.0 error codes, and the ones a gateway adds
A reference for the error codes you will actually see from an RPC endpoint: the standard JSON-RPC 2.0 set, the node-level codes layered on top, and the gateway codes that tell you a limit was enforced before your request ever reached a node.
Error handling is where most RPC client code is thinnest. Part of the reason is that the codes come from three different layers and the specification only defines one of them. This is a reference for all three, and for telling them apart at runtime.
Layer 1: the JSON-RPC 2.0 specification
These are defined by the protocol itself and mean the same thing against any implementation. They describe a malformed or unroutable call, not a failed one.
| Code | Meaning | What it usually indicates |
|---|---|---|
| -32700 | Parse error | The body was not valid JSON — often a serialisation bug on your side |
| -32600 | Invalid request | Valid JSON, but not a valid JSON-RPC 2.0 object |
| -32601 | Method not found | The method does not exist on this chain or is not exposed |
| -32602 | Invalid params | Wrong parameter count, order or type |
| -32603 | Internal error | A generic server-side failure |
The specification also reserves -32000 to -32099 for implementation-defined server errors, which is the range everything below lives in.
Layer 2: node-level errors
These come from the chain client and vary between implementations, so treat their codes as advisory and their messages as the real signal. Common cases are an execution revert during eth_call, a gas estimation failure, a query exceeding the node configured range or result limit, and a request for state the node has pruned.
The important property of this layer is that your request did reach a node. Something about the request or the chain state made it fail there.
Layer 3: gateway errors
A gateway enforces limits before forwarding, so these errors mean your request never reached a node at all. On Iteradian they arrive as an HTTP 429 with a JSON-RPC 2.0 error body:
| Code | Meaning | Correct response |
|---|---|---|
| -32005 | Per-second rate or concurrency ceiling exceeded | Retry after data.retryAfter seconds, with backoff — this clears on its own |
| -32006 | Monthly request quota used up (data.resetsAt says when it resets) | Does not clear by retrying; wait for the reset or upgrade |
| -32007 | Overage spend cap reached for the billing period (data.overageCapUsd) | Does not clear by retrying; raise the cap or change plan |
The error data says what to do next — retryAfter and the allowed limit for -32005, resetsAt for -32006, overageCapUsd for -32007 — so a client can log something actionable instead of "rate limited". Concurrency rejections arrive the same way, as -32005 with data.inFlight: over the ceiling you get a 429 rather than being queued, so a runaway client fails fast instead of backing up behind itself.
One gateway error is not a limit. When every node serving a network fails your request, the gateway answers HTTP 503 with code -32603; when no node is available for the network at all, it answers 503 without a JSON-RPC body. Both are worth retrying with backoff.
Telling the layers apart
The HTTP status is the fastest discriminator. A 429 is always a gateway limit. A 200 with an error member is the node or the protocol. A 400 or 403 is not RPC at all, and its body is not a JSON-RPC envelope but a plain statusCode and message: 400 is a missing API key, a body that is not JSON-RPC or an unknown network slug; 403 is an invalid, revoked or expired key, a request from outside the key IP allowlist, a network the key is not allowed to call, or an organization without an active subscription.
- HTTP 429 → a limit was enforced. Read the code to know which one.
- HTTP 200 with error.code in -32700..-32603 → your request was malformed.
- HTTP 200 with error.code in -32000..-32099 → the node rejected it.
- HTTP 400 or 403 → the key, the network slug or the account, not the call. Do not retry.
- HTTP 503 → no node could serve the network just now. Retry with backoff.
Handling those five cases distinctly is most of what good RPC client code does. Everything else is retries.
Frequently asked questions
01What does JSON-RPC error code -32601 mean?
Method not found. The method you called either does not exist on that chain or is not exposed by the endpoint. It is defined by the JSON-RPC 2.0 specification and means the same thing against any implementation.
02What is the difference between error -32005 and -32006?
Both arrive with HTTP 429 from the Iteradian gateway. -32005 is the per-second rate or concurrency ceiling and clears after the data.retryAfter delay. -32006 means the monthly request quota is used up, and -32007 that the overage spend cap for the period is reached; neither clears by retrying — wait for the reset date, raise the cap or change plan.
03How do I tell a gateway error from a node error?
Use the HTTP status. A 429 is always a limit enforced by the gateway before the request reached a node. A 200 carrying an error member came from the node or from protocol validation. A 400 or 403 is a problem with the API key, the network slug or the account, and its body is not a JSON-RPC envelope.