Para desarrolladores / JSON-RPC

Errores y límites

Cinco códigos de error lo cargan todo. -32005 es el que merece la pena gestionar bien, porque significa un límite en lugar de un error - la misma petición tendrá éxito más tarde.

Los 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

La distinción que importa en la práctica es la que hay entre -32000 y -32005. Un error de ejecución es un hecho sobre su transacción y reintentar no cambia nada; un error de límite es un hecho sobre la carga actual del nodo, y la petición idéntica tendrá éxito en cuanto haya sitio.

Sin error.data

Su biblioteca no puede decodificar las razones de 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.

La página de desviaciones tiene la solución alternativa.

Sending a transaction

Límite	Valor	Variable	Al superarlo
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 compilación	-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 compilación	-32005
Execution waitthe coordinator's own deadline is 5 s; the call waits until the transaction executes or this expires	6 s	constante de compilación	-32005 "transaction timed out waiting for execution"
Per execution batchMAX_ADMIT_PER_BATCH - a throughput mechanism, not a caller-visible limit	512	constante de compilación	-

Expensive reads

Límite	Valor	Variable	Al superarlo
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 compilación	-32005 "log block range is too wide"
eth_getLogs matchesnarrow the filter or walk the range in windows	10,000	constante de compilación	-32005 "eth_getLogs matched too many logs"

The HTTP listener

Límite	Valor	Variable	Al superarlo
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

Límite	Valor	Variable	Al superarlo
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

Dos valores que no son configuración

MIN_GAS_PRICE (1 wei) y EXECUTION_SPEC (Cancun) parecen ajustes y son deliberadamente constantes de compilación.

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.

Gestionar bien los límites

No hay limitación de tasa por cliente ni cabecera de presupuesto restante, así que un cliente no puede autolimitarse a partir de una señal - tiene que portarse bien por construcción. Importan tres cosas:

Espacie los reintentos ante -32005, no reintente de inmediato. El cubo de lecturas pesadas se comparte entre todos los llamantes, así que un bucle de reintento apretado es la forma más rápida de mantenerlo vacío para todo el mundo, usted incluido.
Divida en ventanas sus rangos de eth_getLogs por debajo de 5000 bloques y espere el tope de 10 000 coincidencias. En una cadena que conserva unos dos minutos de bloques, el límite práctico con el que se topa primero es la retención y no el alcance.
Mantenga los lotes en 32. Por encima de eso el lote se rechaza en lugar de truncarse.

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