JSON-RPC -32602 Invalid Params: Validación de argumentos RPC

Qué significa -32602 Invalid params en JSON-RPC 2.0

La especificación JSON-RPC 2.0 define un conjunto fijo de códigos de error, y -32602 Invalid params es uno de ellos. Se devuelve cuando el método existe y el sobre de la solicitud es válido, pero el valor de params es estructural o semánticamente inaceptable para el servidor. Esto es distinto de un error de método no encontrado, que indica que el nombre del método en sí es desconocido.

La especificación establece que params DEBE ser un array (parámetros posicionales) o un objeto (parámetros por nombre). Omitir params por completo solo está permitido para métodos que no toman parámetros. Enviar params: {} a un método que espera argumentos posicionales, o params: [..] a un método que espera un objeto por nombre, produce un -32602 inmediato en un servidor conforme.

La especificación Ethereum JSON-RPC se basa en esto definiendo qué métodos usan arrays posicionales y cuáles aceptan objetos por nombre. La mayoría de los métodos de la capa de ejecución como eth_getBalance, eth_call y eth_getLogs usan arrays posicionales. Algunos clientes además aceptan objetos por nombre para ciertos métodos, pero esto no es universal y varía según el cliente y la versión.

• params DEBE ser un array o un objeto; omitir params solo es válido para métodos sin argumentos.
• -32602 significa que el método fue reconocido pero los argumentos fueron rechazados.
• La especificación no exige que el servidor nombre el parámetro problemático en el mensaje de error.
• La tolerancia específica del proveedor para params por nombre está documentada / varía según el proveedor.

Params posicionales versus por nombre y el límite de tolerancia del cliente

La especificación Ethereum JSON-RPC usa arrays posicionales para casi todos los métodos estándar. Por ejemplo, eth_getBalance toma [address, blockTag]. Un cliente que solo implementa params posicionales devolverá -32602 si envías {"address": "0x...", "blockTag": "latest"} como objeto, aunque el método exista y los valores sean correctos.

Algunos clientes, incluidas ciertas versiones de Geth y Erigon, aceptan objetos por nombre para un subconjunto de métodos como conveniencia. Esto no está garantizado por la especificación y puede cambiar entre versiones. Una solicitud que pasa en un endpoint puede fallar en otro tras cualquier actualización, por lo que depender de params por nombre en código de producción es riesgoso.

La tabla a continuación resume el límite. Trata la columna 'por nombre aceptado' como documentada / varía según el proveedor, no como una garantía fija.

• Los arrays posicionales son la forma portátil y alineada con la especificación para los métodos de Ethereum.
• Los objetos por nombre pueden funcionar en algunos clientes pero no son universalmente compatibles.
• Un cliente que solo implementa params posicionales devuelve -32602 para un objeto por nombre.
• Prueba siempre contra tu endpoint y versión de cliente específicos.

// Comparison of params forms for eth_getBalance
// Positional (portable):
{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "latest"],
  "id": 1
}

// By-name (may return -32602 on some clients):
{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": {"address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "blockTag": "latest"},
  "id": 1
}

Codificación hex quantity y data como la causa más común en el mundo real

La especificación Ethereum JSON-RPC distingue entre codificaciones QUANTITY y DATA. Los valores QUANTITY deben tener prefijo 0x, usar la menor cantidad posible de dígitos hexadecimales y no tener ceros a la izquierda. Los valores DATA deben tener prefijo 0x y longitud par. Un 1000 decimal donde la especificación requiere 0x3e8 es una causa frecuente de -32602, al igual que una cantidad como 0x03e8 con un cero a la izquierda.

La concatenación de cadenas suele ser el culpable. Construir una cadena hex con '0x' + number.toString(16) funciona para casos simples pero falla cuando el número es cero (produce '0x0', que es válido) o cuando la lógica de relleno introduce ceros a la izquierda. Usa un codificador dedicado como hexlify de ethers.js o toHex de viem para evitar estos errores.

El uso de mayúsculas en las direcciones también importa. La especificación acepta direcciones en minúsculas y con checksum, pero algunos clientes rechazan direcciones totalmente en mayúsculas o con mayúsculas mixtas que no coinciden con el checksum EIP-55. Normalizar las direcciones con getAddress de ethers.js o getAddress de viem previene esta clase de -32602.

• QUANTITY: prefijo 0x, sin ceros a la izquierda, dígitos hex mínimos.
• DATA: prefijo 0x, hex de longitud par.
• Usa hexlify / toHex en lugar de concatenación manual de cadenas.
• Normaliza las direcciones a minúsculas o a un checksum EIP-55 válido antes de enviar.

// Correct encoding with ethers.js v6
import { hexlify, getAddress } from 'ethers';

const blockNumber = 1000;
const quantity = hexlify(blockNumber); // '0x3e8'
const address = getAddress('0x742d35cc6634c0532925a3b844bc454e4438f44e');

// Incorrect: decimal where hex is required
// const badQuantity = 1000; // -32602

// Incorrect: leading zero in quantity
// const badQuantity2 = '0x03e8'; // -32602 on strict clients

Una función de validación previa al envío para clientes Node.js

Validar los argumentos antes de que la solicitud salga de tu proceso es la forma más efectiva de evitar -32602. La función a continuación verifica la aridad, el formato de hex-quantity, el uso de mayúsculas en direcciones y la validez de block tags para un pequeño conjunto de métodos comunes. Amplía el mapa de esquemas a medida que agregues métodos.

El validador devuelve un array de cadenas de error. Si el array está vacío, la solicitud es segura de enviar. Esto no sustituye la validación del lado del servidor, pero captura la mayoría de los errores del lado del cliente antes de que consuman un viaje de ida y vuelta.

• Verifica la aridad contra el número esperado de parámetros del método.
• Valida los campos QUANTITY con una expresión regular que rechace ceros a la izquierda.
• Valida las direcciones con una expresión regular y opcionalmente con el checksum EIP-55.
• Valida los block tags contra el conjunto permitido o un número de bloque en hex.

// validateParams.js — drop-in pre-flight validator
const QUANTITY_RE = /^0x([1-9a-f][0-9a-f]*|0)$/;
const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
const BLOCK_TAGS = new Set(['latest', 'safe', 'finalized', 'earliest', 'pending']);

const SCHEMAS = {
  eth_getBalance: { arity: 2, types: ['address', 'blockTag'] },
  eth_getTransactionCount: { arity: 2, types: ['address', 'blockTag'] },
  eth_call: { arity: 2, types: ['object', 'blockTag'] },
  eth_getLogs: { arity: 1, types: ['object'] },
  eth_blockNumber: { arity: 0, types: [] },
};

function validateParams(method, params) {
  const errors = [];
  const schema = SCHEMAS[method];
  if (!schema) return [`Unknown method: ${method}`];
  if (!Array.isArray(params)) {
    errors.push('params must be an array for this method');
    return errors;
  }
  if (params.length !== schema.arity) {
    errors.push(`Expected ${schema.arity} params, got ${params.length}`);
  }
  schema.types.forEach((type, i) => {
    const v = params[i];
    if (type === 'address' && !ADDRESS_RE.test(v)) errors.push(`param[${i}] invalid address`);
    if (type === 'blockTag') {
      const ok = BLOCK_TAGS.has(v) || QUANTITY_RE.test(v) || /^0x[0-9a-fA-F]{64}$/.test(v);
      if (!ok) errors.push(`param[${i}] invalid block tag`);
    }
    if (type === 'object' && (typeof v !== 'object' || v === null)) errors.push(`param[${i}] must be an object`);
  });
  return errors;
}

// Usage
const errs = validateParams('eth_getBalance', ['0x742d35Cc6634C0532925a3b844Bc454e4438f44e', 'latest']);
if (errs.length) console.error('Pre-flight failed:', errs);
else console.log('Request is safe to send');

Distinguir -32602 de los códigos de error vecinos

El triaje rápido depende de saber qué capa falló. -32600 Invalid Request significa que el sobre en sí está mal formado: versión jsonrpc incorrecta, método faltante o un id de tipo inválido. -32602 significa que el sobre está bien pero los argumentos son incorrectos. -32603 Internal error significa que el servidor encontró una falla al procesar una solicitud válida.

Los códigos del rango -32000 están reservados para errores del servidor definidos por la implementación. En los clientes de Ethereum, a menudo representan condiciones específicas de la cadena, como un bloque fuera de rango, un filtro no encontrado o una transacción rechazada por el pool. Por ejemplo, una llamada eth_getLogs con un rango de bloques que excede el límite del nodo puede devolver un error del rango -32000 en lugar de -32602, porque los argumentos son estructuralmente válidos pero el rango solicitado no es atendible. Consulta límites de rango de bloques en eth_getLogs y escaneos grandes para ese caso específico.

Si no estás seguro de si una falla es -32602 o -32603, reproduce la llamada exacta con curl e inspecciona el objeto de error. El campo code es autoritativo; el campo message no está estandarizado y puede estar vacío o ser engañoso.

• -32600: sobre mal formado (versión jsonrpc incorrecta, tipo de id incorrecto).
• -32602: solicitud bien formada, argumentos inaceptables.
• -32603: falla del lado del servidor al procesar una solicitud válida.
• Rango -32000: condiciones específicas del nodo/cadena, como un bloque fuera de rango.

Aislar un -32602 con curl y repetición incremental

Cuando una llamada falla con -32602, la ruta más rápida hacia el argumento problemático es reproducir la solicitud exacta con curl, luego quitar los params opcionales y volver a agregarlos uno a la vez. Comienza con la solicitud completa para confirmar el error, luego elimina el último parámetro y reintenta. Si el error desaparece, el parámetro eliminado es el culpable.

Para métodos con parámetros opcionales, como eth_getLogs con fromBlock y toBlock, prueba cada combinación. Algunos clientes rechazan null donde se requiere un valor, y otros aceptan null como predeterminado. Documenta qué comportamiento exhibe tu endpoint.

El ejemplo de curl a continuación envía una solicitud mínima de eth_getBalance. Reemplaza la URL con tu endpoint RPC y ajusta los params para reproducir tu falla.

• Reproduce la llamada fallida exacta con curl para confirmar el código de error.
• Elimina los params opcionales, luego vuelve a agregarlos uno a la vez.
• Prueba null versus omitido para campos opcionales.
• Registra la forma exacta de params que desencadena -32602.

curl -X POST https://your-endpoint.example \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "latest"],
    "id": 1
  }'

Documentar la tolerancia de tu endpoint con una tabla de resultados

Debido a que las reglas de validación varían según el cliente y la versión, la única forma confiable de saber qué acepta tu endpoint es medirlo. Construye una pequeña matriz de métodos, formas de params y resultados esperados, luego ejecútala contra cada endpoint del que dependas. Completa la tabla a continuación con tus propios resultados.

Ejecuta cada fila como una solicitud separada y registra el estado HTTP, el código de error JSON-RPC y el mensaje. Esto te da una línea base de regresión que puedes volver a ejecutar después de actualizaciones del cliente. La tabla está intencionalmente vacía; los valores son para que los midas tú, no para que nosotros los afirmemos.

• Method: el nombre del método JSON-RPC.
• Client: el software del nodo y la versión detrás del endpoint.
• Params form: array posicional u objeto por nombre.
• Accepted?: sí o no.
• Code: el código de error JSON-RPC devuelto, si lo hay.
• Message: el texto del mensaje de error, si lo hay.

| Method | Client | Params form | Accepted? | Code | Message |
|--------|--------|-------------|-----------|------|---------|
| eth_getBalance | Geth v1.x | positional | | | |
| eth_getBalance | Geth v1.x | by-name | | | |
| eth_getBalance | Erigon v2.x | positional | | | |
| eth_getBalance | Erigon v2.x | by-name | | | |
| eth_call | Geth v1.x | positional | | | |
| eth_getLogs | Geth v1.x | positional | | | |

Lista de verificación de solución de problemas para -32602

Trabaja a través de la siguiente lista de verificación en orden. La mayoría de los errores -32602 son causados por uno de estos problemas, y la lista está ordenada por frecuencia de ocurrencia en la práctica.

Si ninguno de estos resuelve el error, el problema puede ser la tolerancia específica del cliente. Compara tu solicitud con la especificación Ethereum JSON-RPC y la especificación JSON-RPC 2.0 para confirmar la forma esperada de params.

• Orden incorrecto de parámetros: los arrays posicionales son sensibles al orden.
• Codificación quantity versus data: 0x3e8 es una quantity; 0x03e8 es inválido.
• null donde se requiere un valor: algunos clientes rechazan null para campos obligatorios.
• Dirección sin prefijo 0x: incluye siempre el prefijo.
• Block tag que el nodo no admite: safe y finalized pueden no estar disponibles en todas las cadenas.
• Objeto por nombre enviado a un cliente solo posicional.
• Ceros a la izquierda en una quantity hex.
• Parámetro obligatorio faltante por completo.

Limitaciones y compensaciones de la validación del lado del cliente

La especificación JSON-RPC 2.0 no exige un mensaje de error informativo. Un servidor puede devolver -32602 sin indicar qué parámetro falló, lo que significa que la validación del lado del cliente es la única forma de obtener un diagnóstico preciso. Esta es una limitación del protocolo, no de ningún proveedor específico.

Las reglas de validación también varían según la versión del cliente. Una solicitud que pasa en un endpoint puede fallar en otro tras cualquier actualización, y un objeto por nombre que funciona hoy puede ser rechazado después de una actualización del nodo. Mantener un mapa de esquemas para cada método que llamas es trabajo continuo, pero es más barato que depurar fallas en producción.

Finalmente, la validación del lado del cliente no puede detectar errores semánticos que solo el servidor puede evaluar, como un número de bloque que es hex válido pero está más allá de la cabeza de la cadena. Esos casos devuelven errores del rango -32000, no -32602, y requieren un manejo diferente. Para llamadas dependientes del estado, consulta anulaciones de estado y simulación en eth_call.

• La especificación no exige que el servidor nombre el parámetro problemático.
• Las reglas de validación varían según la versión del cliente y pueden cambiar en cualquier actualización.
• La validación del lado del cliente no puede detectar errores semánticos del lado del servidor.
• Mantener un mapa de esquemas es trabajo continuo pero reduce las fallas en producción.

Próximos pasos para un manejo robusto de argumentos RPC

Comienza agregando el validador previo al envío a tu cliente y ejecutándolo contra tus métodos más usados. Luego construye la tabla de resultados para cada endpoint del que dependas y vuelve a ejecutarla después de las actualizaciones del cliente. Esto te da una línea base de regresión y una imagen clara de la tolerancia de tu endpoint.

Para temas relacionados, consulta Gestión de nonce con eth_getTransactionCount para el manejo de argumentos de conteo de transacciones, y Filtrado de eventos y topics en eth_getLogs para la validación de argumentos de filtros. Si estás eligiendo un endpoint, la guía de endpoints RPC cubre los criterios de selección de endpoints.

Para explorar redes y endpoints compatibles, visita la página de la red Ethereum, el centro de aprendizaje de OnFinality, o revisa los precios de RPC y el servicio de API para opciones de integración.

• Agrega el validador previo al envío a tu cliente.
• Construye y vuelve a ejecutar la tabla de resultados después de las actualizaciones.
• Revisa guías relacionadas de manejo de argumentos para otros métodos.
• Elige endpoints que coincidan con tus requisitos de forma de params.