Which JSON-RPC Errors Are Retryable

By John Sullivan · November 15, 2026 · 9 min read · #json-rpc error retryable

Most JSON-RPC errors are safe to retry. A few are not, and retrying them makes things worse. The failure that costs the most is not an error at all: it arrives as HTTP 200, with a result that parses, and it is out of date.

So whether a JSON-RPC error is retryable is a three-way question — transient, terminal, or terminal for the payload you sent — and getting all three right is necessary but not sufficient. A client can classify every error correctly and still write wrong data, because the worst case raises nothing to handle.

Two layers, and only one of them is an error

JSON-RPC is transport agnostic: the specification says the same concepts work over sockets, over HTTP, or inside a single process [1]. The HTTP status and the JSON-RPC error object are separate layers, and neither implies the other.

A 200 can carry an error object. In our service a method that does not exist on a chain usually comes back as -32601 with HTTP 200, not as a 4xx, so a client that branches on response.status alone never reads the error member. A 200 can also carry a result that is stale, and a client that branches on the error member alone never notices.

The specification requires the error member to be an object [1], and its examples show code and message [1]. Codes from -32768 to -32000 are reserved for pre-defined errors, and -32000 to -32099 specifically for implementation-defined server errors [2]. Several of the codes here sit in that range, which is why a number alone tells you less than you want.

The code says what went wrong. It does not say whether sending the request again will help. For the code-by-code reference, see our error-code taxonomy.

Three states, not two

A 429 with a Retry-After and a -32602 do not belong in the same column, and neither belongs with -32005. This classification is one provider's, not the protocol's: JSON-RPC assigns no retry semantics to any code, and the -32000 to -32099 block is explicitly implementation-defined [2].

Transient. Waiting and sending again gets a different answer. Members: HTTP 429 with a Retry-After header [3]; a transport timeout that produced no valid response at all, which tends to arrive as a 502; a 502 backend node error; a 503 whose message reads usage check temporarily unavailable, which is our own wording.

Terminal. No amount of waiting turns this into a different answer. Members: -32601 method not found [2]; -32602 invalid params [2]; an execution revert; a plan gate returning 403 with -33000; a 502 saying no archive node is available for that chain; a monthly allowance that has run out.

Terminal for this payload. The request as written will fail again, but the request is the problem rather than the moment. One member: the heavy-query timeout, which comes back as -32005.

-32005 is server-defined

-32005 is not in the JSON-RPC 2.0 specification, and not among the implementation-defined constants in geth's rpc/errors.go [2][4]. It sits inside the reserved -32000 to -32099 range [2], so its meaning is whatever the server that emits it says. Read the message, not the number.

Here it means the query was too heavy to finish inside the node's budget. Waiting does not make the query cheaper, so a second attempt at the same shape meets the same budget. What changes the outcome is the request: a shorter span of blocks, or an address filter that cuts the logs the node has to scan.

A two-column retryable-or-not table cannot hold this. The row would have to say no and yes at once, and whichever you pick, some reader follows it into a wall.

The 429 that is not retryable

429 means the client sent too many requests in a given amount of time [3]. The specification that defines it also says it does not define how the server identifies the user or how it counts requests [5]. That gap is the problem: one status code covers a per-second throttle and a monthly allowance that has run out, and the two need opposite responses.

A per-second throttle clears. Wait for the interval the server gives you and send again. Retry-After is permitted on a 429, not required [3], so a client that waits for a header that never arrives waits forever — fall back to your own backoff when it is absent. The header is defined in RFC 9110 §10.2.3 [6]; read the value as the server sent it rather than assuming a unit.

A monthly allowance does not clear until the UTC reset. Ours answers with a 429 whose body names resetsAt and a retryAfter far longer than any throttle window, and waiting inside the current period changes nothing. Retrying it spends requests against a wall that is already down. Read resetsAt, schedule the work after it, and treat everything in between as terminal.

How many times, and what is safe to resend

A retry loop needs a stop condition that is a fact about the request, not a count. For a block ahead of the head, the head reaching that block. For an allowance, the reset time. For a terminal error, the first response. A cap on attempts is a backstop for when none of those can be met; make it explicit so a stuck loop fails loudly.

Backoff mechanics — how the delay grows, how jitter is applied — are in 429, backoff and jitter. What matters here is what is safe to send twice.

A transaction send is the one that can cost money. If eth_sendRawTransaction times out, the transaction may already be in a pool, and the timeout says nothing about which. Check the hash before resending. A node that already holds the transaction answers with a duplicate-transaction error rather than accepting it [7][8], and the same signed transaction cannot be included twice on-chain, because consensus requires the account nonce to equal the transaction nonce exactly [9] — once it is included, a resubmission is rejected because the account nonce has already advanced.

The pool is per-node, though. That duplicate error is true of the node that holds the transaction, not of the network, so a second endpoint may accept the same signed transaction without complaint [7]. That is not a double spend, for the nonce reason above, but it is a second copy in a second pool.

The failures that are not errors

A request the node cannot answer does not always come back as an error. Which shape you get depends on the method and on how far ahead of the head you asked.

An explicit future block. Ask for a block number above the head and you get an error: block not found: 26328964, with -32000. That message is ours.

A log range beyond the head. eth_getLogs with a toBlock above the head is an error, and the message is block range extends beyond current head block [10]. The specification is explicit that clients must return an invalid-params error here and must not clamp the range to the head or return a partial result [11]. In geth the code attached to that message is -32602 [12], and the check fires when the range's last block is above the head [13]. Match on the message rather than the code.

A block beyond the head, asked for by number. eth_getBlockByNumber for a block the node does not have returns result: null, not an error. The result schema is a choice between a null and a block [14], and the null is a first-class part of the schema [15]. geth returns a nil block and a nil error in that case [16]. Two independent sources, same answer.

latest on a node that is behind. This is the one with no error and no null. A node a few blocks behind its peers answers a latest query with a result that is well-formed, correctly typed, and older than the chain, and nothing in the response says so. Routing does not rescue you here: an answer that came back successfully is treated as an answer, and its age is not a reason to send the request somewhere else.

Nothing in the protocol backs that last sentence. JSON-RPC defines no freshness semantics for any method [1], so a stale latest is a property of a deployment rather than a violation of a standard — which is why no error code exists for it.

Detecting a stale answer

No field in the response, and no server-side record you can query, ties an answer to how far behind the node was. The check lives in the client, and there are two ways to build it.

Compare the block number in the response against a head you trust. Every block-returning method gives you a number, and eth_blockNumber gives you the node's own view. If the two disagree by more than your tolerance, the answer is stale and the request should go to a different endpoint — ordered, weighted and quorum failover covers how to choose one. This costs one extra call per batch, and it is the only check that catches the latest case.

Pin the block. For the six state-query methods that accept it, the block parameter can be an object with either blockNumber or blockHash [17] — eth_getBalance, eth_getStorageAt, eth_getTransactionCount, eth_getCode, eth_call and eth_getProof [18]. A hash the node does not have should raise an error, with -32001 recommended [19], and requireCanonical turns a reorged-out block into a distinguishable error [20]. Pinning works because the client holds the consistency state instead of asking the node to keep it [21].

Pinning has a limit. It detects a reorg of the block you pinned; it does not tell you the node is behind [21].

For the explicit future-block case, do not retry on a timer. Poll eth_blockNumber and send the request again when the head reaches the block you asked for. Block production runs on a cadence the chain's own configuration sets [22], so the wait is a function of the chain rather than a constant you pick. For block not found, back off with jitter; if the block is far ahead of the head, it may not be a block that will ever exist.

What this does not fix

Handling every error correctly still leaves the stale case, because the stale case is not an error. The taxonomy tells you what to do with a response that failed. It says nothing about a response that succeeded and is wrong, and no retry policy closes that gap — only a freshness check does.

Read the rate-limit guide

Sources

  1. JSON-RPC 2.0 Specification — Error Object — JSON-RPC Working Group (jsonrpc.org), 2010-01-01
  2. JSON-RPC 2.0 Specification — reserved error code range — JSON-RPC Working Group (jsonrpc.org), 2010-01-01
  3. RFC 6585 §4 — 429 Too Many Requests — IETF / RFC Editor, 2012-04-01
  4. go-ethereum rpc/errors.go — implementation-defined error code constants — ethereum/go-ethereum (GitHub)
  5. RFC 6585 §4 — counting rule is implementation-defined — IETF / RFC Editor, 2012-04-01
  6. IANA HTTP Field Name Registry — Retry-After is defined in RFC 9110 §10.2.3 — IANA
  7. go-ethereum core/txpool/legacypool/legacypool.go — add() rejects an already-known transaction — ethereum/go-ethereum (GitHub)
  8. go-ethereum core/txpool/errors.go — ErrAlreadyKnown — ethereum/go-ethereum (GitHub)
  9. execution-specs forks/cancun/fork.py — check_transaction requires exact nonce equality — ethereum/execution-specs (GitHub)
  10. go-ethereum eth/filters/api.go — error variable declarations — ethereum/go-ethereum (GitHub)
  11. execution-apis src/eth/filter.yaml — eth_getLogs description — ethereum/execution-apis (GitHub)
  12. go-ethereum eth/filters/api.go — invalidParamsError carries code -32602 — ethereum/go-ethereum (GitHub)
  13. go-ethereum eth/filters/filter.go — where the beyond-head range check fires — ethereum/go-ethereum (GitHub)
  14. execution-apis src/eth/block.yaml — eth_getBlockByNumber result schema — ethereum/execution-apis (GitHub)
  15. execution-apis src/schemas/base-types.yaml — notFound schema — ethereum/execution-apis (GitHub)
  16. go-ethereum internal/ethapi/api.go — GetBlockByNumber returns nil,nil when the block is absent — ethereum/go-ethereum (GitHub)
  17. EIP-1898: Add blockHash to defaultBlock methods — Specification — Ethereum Improvement Proposals, 2019-04-01
  18. EIP-1898 — affected methods list — Ethereum Improvement Proposals, 2019-04-01
  19. EIP-1898 — block-not-found error and requireCanonical — Ethereum Improvement Proposals, 2019-04-01
  20. EIP-1898 — requireCanonical semantics — Ethereum Improvement Proposals, 2019-04-01
  21. EIP-1898 — rationale for pinning a block hash — Ethereum Improvement Proposals, 2019-04-01
  22. consensus-specs configs/mainnet.yaml — slot duration and Eth1 block estimate — ethereum/consensus-specs (GitHub)

This article was researched, written and edited by AI under human supervision, and checked against Rankwrite's public editorial rubric.

J
John Sullivan
Infrastructure Writer, SwiftNodes

John Sullivan covers RPC infrastructure, node operations, and multi-chain development at SwiftNodes — what it actually takes to keep endpoints fast, fresh, and reliable across EVM and non-EVM networks.

Try SwiftNodes free — multi-chain RPC across 139 networks, flat-rate pricing, pay by card or crypto, no KYC. Get an API key in 30 seconds →