Para desenvolvedores / JSON-RPC

Erros e limites

Cinco códigos de erro carregam tudo. -32005 é o que vale a pena tratar bem, porque ele significa um limite e não um erro - o mesmo pedido terá sucesso mais tarde.

Os cinco códigos

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

A distinção que importa na prática é a que separa -32000 de -32005. Um erro de execução é um fato sobre a sua transação e tentar de novo não muda nada; um erro de limite é um fato sobre a carga atual do nó, e o pedido idêntico terá sucesso assim que houver espaço.

Sem error.data

As razões de revert não podem ser decodificadas pela sua biblioteca

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.

A página das diferenças traz a solução de contorno.

Sending a transaction

Limite	Valor	Variável	Em caso de violação
Raw transaction sizechecked on the hex string BEFORE decoding, so an oversized transaction is a limit error rather than a decode error	128 KiB	constante de compilação	-32005
Admission queuequeued transactions across all senders	4,096 total	ADMISSION_CAPACITY	-32005 "sequencer admission queue is full"
Per sendercompile-time, so one sender cannot fill the queue with unfillable nonces	64	constante de compilação	-32005
Execution waitthe coordinator's own deadline is 5 s; the call waits until the transaction executes or this expires	6 s	constante de compilação	-32005 "transaction timed out waiting for execution"
Per execution batchMAX_ADMIT_PER_BATCH - a throughput mechanism, not a caller-visible limit	512	constante de compilação	-

Expensive reads

Limite	Valor	Variável	Em caso de violação
Token bucket burstguards eth_call, eth_estimateGas and eth_getLogs together	256	HEAVY_READ_BURST	-32005 "rate limit exceeded for expensive read methods"
Refill rateprocess-wide and shared by every caller - explicitly a backstop, not per-client limiting	128/s	HEAVY_READ_PER_SEC	-
eth_getLogs spana span of 5,000 or more is refused outright	under 5,000 blocks	constante de compilação	-32005 "log block range is too wide"
eth_getLogs matchesnarrow the filter or walk the range in windows	10,000	constante de compilação	-32005 "eth_getLogs matched too many logs"

The HTTP listener

Limite	Valor	Variável	Em caso de violação
Connections	512	RPC_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 calls	2 MiB	RPC_MAX_REQUEST_BYTES	-
Response body	16 MiB	RPC_MAX_RESPONSE_BYTES	-
Batch lengthsplit a larger batch client-side	32	RPC_MAX_BATCH	-
Keep-aliveTCP_NODELAY is on	30 s	RPC_KEEP_ALIVE_SECS	-

Filters

Limite	Valor	Variável	Em caso de violação
Filters per node	1,024	MAX_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 end	1,024 entries	MAX_FILTER_BUFFER	-
Idle expirymeasured since the last poll, and expiry is silent - the next poll answers -32602 "filter not found"	300 s	FILTER_TTL_SECS	-32602

Dois valores que não são configuração

MIN_GAS_PRICE (1 wei) e EXECUTION_SPEC (Cancun) parecem ajustes e são deliberadamente constantes de compilação.

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.

Lidar bem com os limites

Não há limitação de taxa por cliente nem cabeçalho de orçamento restante, então um cliente não pode se autolimitar a partir de um sinal - ele tem de ser bem-comportado por construção. Três coisas importam:

Recue no -32005, não tente de novo imediatamente. O balde de leituras pesadas é compartilhado entre todos os chamadores, então um laço de retentativa apertado é a maneira mais rápida de mantê-lo vazio para todo mundo, você incluído.
Janele seus intervalos de eth_getLogs abaixo de 5.000 blocos e espere o teto de 10.000 correspondências. Numa cadeia que conserva cerca de dois minutos de blocos, o limite prático que você encontra primeiro é a retenção e não o alcance.
Mantenha os lotes em 32. Acima disso o lote é rejeitado em vez de truncado.

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;
}