開発者へ / JSON-RPC

エラーと制限

五つのエラーコードがすべてを運びます。きちんと扱う価値があるのは -32005 です。間違いではなく制限を意味しており、同じリクエストが後で成功するからです。

五つのコード

コードValue
-32602Invalid paramsa malformed address, block tag, filter id or topic filter
-32601Method not found or not availablean unregistered name, or one refused by design such as eth_sendTransaction
-32000Executiona revert, a decode failure, a signature failure, or a consensus rejection
-32005Limita rate limit, a full queue, a timeout, a size cap or a filter cap - every row on this page
-32603Internala write-ahead-log or coordinator failure; also every non-send error when you are on the WebSocket transport

運用上で効いてくる区別は -32000 と -32005 の間にあります。実行 エラーはあなたのトランザクションについての事実であり、再試行しても何も変わりません。制限 エラーはノードの現在の負荷についての事実であり、空きができれば同一のリクエストが成功します。

error.data はない

revert の理由はあなたのライブラリではデコードできません

A revert arrives as message text - "execution reverted: 0x<returndata>" - and error.data is absent.

Libraries decode custom errors and revert strings out of error.data, so on this chain they cannot. ethers and viem will both surface the raw message instead of a decoded error. If you need the reason, parse the hex out of the message yourself and decode it against your own ABI.

相違点のページに回避策があります。

Sending a transaction

制限値変数超過時
Raw transaction sizechecked on the hex string BEFORE decoding, so an oversized transaction is a limit error rather than a decode error128 KiBコンパイル時定数-32005
Admission queuequeued transactions across all senders4,096 totalADMISSION_CAPACITY-32005 "sequencer admission queue is full"
Per sendercompile-time, so one sender cannot fill the queue with unfillable nonces64コンパイル時定数-32005
Execution waitthe coordinator's own deadline is 5 s; the call waits until the transaction executes or this expires6 sコンパイル時定数-32005 "transaction timed out waiting for execution"
Per execution batchMAX_ADMIT_PER_BATCH - a throughput mechanism, not a caller-visible limit512コンパイル時定数-

Expensive reads

制限値変数超過時
Token bucket burstguards eth_call, eth_estimateGas and eth_getLogs together256HEAVY_READ_BURST-32005 "rate limit exceeded for expensive read methods"
Refill rateprocess-wide and shared by every caller - explicitly a backstop, not per-client limiting128/sHEAVY_READ_PER_SEC-
eth_getLogs spana span of 5,000 or more is refused outrightunder 5,000 blocksコンパイル時定数-32005 "log block range is too wide"
eth_getLogs matchesnarrow the filter or walk the range in windows10,000コンパイル時定数-32005 "eth_getLogs matched too many logs"

The HTTP listener

制限値変数超過時
Connections512RPC_MAX_CONNECTIONS-
Request bodythe public vhost caps a request at 1 MiB before this applies, and 1 MiB of JSON-RPC batch is already thousands of calls2 MiBRPC_MAX_REQUEST_BYTES-
Response body16 MiBRPC_MAX_RESPONSE_BYTES-
Batch lengthsplit a larger batch client-side32RPC_MAX_BATCH-
Keep-aliveTCP_NODELAY is on30 sRPC_KEEP_ALIVE_SECS-

Filters

制限値変数超過時
Filters per node1,024MAX_FILTERS-32005 "filter limit reached"
Buffer per filterthe OLDEST entries are trimmed when you stop polling, so a slow poller loses the beginning of its backlog rather than the end1,024 entriesMAX_FILTER_BUFFER-
Idle expirymeasured since the last poll, and expiry is silent - the next poll answers -32602 "filter not found"300 sFILTER_TTL_SECS-32602

設定ではない二つの値

MIN_GAS_PRICE (1 wei) と EXECUTION_SPEC (Cancun)は設定のように見えますが、意図的にコンパイル時定数になっています。

Both are compile-time constants rather than environment variables, and that is a correctness requirement rather than an oversight. Either one made operator-tunable would let a replica reject or re-price a transaction the leader had accepted, and derivation would halt on the divergence. Pinning the hardfork also means a revm upgrade cannot silently change gas accounting underneath an already-settled chain.

制限とうまく付き合う

クライアントごとのレート制限も、残り予算のヘッダーもありません。だからクライアントは信号を 見て自分を絞ることができず、作りからして行儀よくあるほかありません。効くのは三つです。

  • -32005 ではバックオフし、すぐに再試行しないこと。重い 読み取りのバケツはすべての呼び出し側で共有されるので、詰めた再試行のループは、自分を 含む全員のためにそれを空のままにしておく最速の方法です。
  • eth_getLogs の範囲は窓で区切ること。5,000 ブロックより 下に抑え、10,000 件という一致数の上限を見込んでください。およそ 2 分ぶんのブロックしか 保持しないチェーンでは、先にぶつかる実際的な制限は範囲ではなく保持のほうです。
  • バッチは 32 までに。それを超えるとバッチは切り詰められるのではなく 拒否されます。
javascript
// RPC_URL: https://rpc.picklechain.xyz on the public testnet, or a node of your own.
async function call(body, attempt = 0) {
  const res = await fetch(RPC_URL, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });
  const json = await res.json();

  // -32005 is a limit, not a mistake: the same request works later.
  if (json.error?.code === -32005 && attempt < 5) {
    await new Promise((r) => setTimeout(r, 2 ** attempt * 250));
    return call(body, attempt + 1);
  }
  return json;
}