JSON-RPC -32603 Error interno: causas y depuración

Semántica de la especificación del código de error -32603

La especificación JSON-RPC 2.0 define un rango de error reservado de -32768 a -32000 y asigna a -32603 el mensaje "Internal error" (especificación JSON-RPC 2.0). La especificación describe esto como un error del servidor: la solicitud fue recibida y analizada, pero el servidor encontró una condición inesperada mientras la procesaba. Es deliberadamente genérico. La especificación no requiere una causa específica, solo que el servidor no pudo completar la llamada al método.

La especificación JSON-RPC de Ethereum se basa en esa base y documenta el comportamiento de errores a nivel de método para llamadas como eth_call y eth_estimateGas (especificación JSON-RPC de Ethereum). En la práctica, los clientes de ejecución asignan muchas excepciones internas a -32603, incluidos fallos de decodificación de parámetros, combinaciones de argumentos no soportadas y pánicos dentro del manejador del método. Por eso el código por sí solo rara vez identifica el fallo.

Para una orientación más amplia sobre el comportamiento de endpoints y la selección de proveedores, consulta la guía de endpoints RPC y el centro de aprendizaje de OnFinality.

• -32603 es un error del servidor, no un error del cliente, en la taxonomía JSON-RPC 2.0.
• El mensaje es fijo como "Internal error" pero la causa está definida por la implementación.
• El código está reservado por la especificación y no debe reutilizarse para errores específicos de la aplicación.

Tabla de clasificación: -32603 frente a códigos de error vecinos

Distinguir -32603 de los códigos adyacentes es el primer paso de diagnóstico. -32602 (Invalid params) significa que la estructura de la solicitud se entendió pero los parámetros fallaron la validación. -32601 (Method not found) significa que el nodo no expone ese método. El rango -32000 está reservado para errores del servidor definidos por la implementación, y muchos clientes de ejecución lo usan para reversiones de ejecución y fallos relacionados con el estado.

La siguiente tabla resume la distinción documentada. Trata las entradas del rango -32000 como comportamiento documentado que varía según el cliente y el proveedor, porque la especificación deja su significado exacto a la implementación.

• -32603 Internal error: excepción del lado del servidor durante la ejecución del método; causa no especificada.
• -32602 Invalid params: forma o tipo de parámetro rechazado antes de la ejecución.
• -32601 Method not found: nombre de método no soportado por el nodo.
• Rango -32000: definido por la implementación; comúnmente usado para reversiones de ejecución y errores de estado.
• -32603 es el menos específico de estos y, por lo tanto, el más difícil de ramificar.

Por qué -32603 es una señal genérica

Cualquier excepción lanzada dentro del manejador de método de un nodo puede colapsar en -32603. Un objeto params malformado, una combinación no soportada de argumentos, un nodo quedándose sin memoria o el balanceador de carga de un proveedor fallando al enrutar la solicitud pueden producir el mismo código. La especificación no requiere que el servidor exponga la excepción subyacente, por lo que el código es un síntoma, no un diagnóstico.

Esta generalidad es la razón por la que los hilos de foro sobre -32603 a menudo contienen soluciones contradictorias. El -32603 de un usuario es un error de serialización en su cliente; el de otro es un proxy ascendente que devuelve un fallo de autenticación con el código incorrecto. El único enfoque confiable es bisecar la ruta de la solicitud hasta aislar la capa que falla.

Método de bisección de tres capas para aislar el fallo

Bisecar significa eliminar capas hasta que el error cambie o desaparezca. Comienza con una solicitud curl sin procesar que evite por completo tu biblioteca de aplicación. Si la solicitud sin procesar tiene éxito, el fallo está en el código de tu cliente o en su serialización. Si falla, el fallo está en el nodo o en la ruta del proveedor.

A continuación, reproduce la llamada fallida como eth_call con campos explícitos from, to, value y gas. Los fallos de estimación son el disparador más común de -32603 en producción, y eth_call con gas explícito a menudo devuelve una carga útil de reversión decodificable en lugar de un error interno genérico. Finalmente, decodifica el campo data si está presente. Un selector de reversión o un error personalizado en data te dice que la llamada llegó a la EVM y falló allí, lo que apunta a la lógica del contrato en lugar de a la infraestructura.

Para detalles específicos de decodificación de reversiones, consulta Decodificación de razones de reversión y errores personalizados de Ethereum.

• Capa 1: curl sin procesar con una solicitud mínima y bien formada.
• Capa 2: eth_call con gas explícito y campos de llamada completos.
• Capa 3: decodificar el campo data en busca de un selector de reversión o error personalizado.
• Si el error cambia entre capas, la última capa que eliminaste está implicada.

Ejemplo ejecutable en Node.js que imprime el objeto de error sin procesar

Las bibliotecas de cliente como ethers y viem envuelven -32603 y a menudo ocultan la carga útil de data. El siguiente ejemplo emite una solicitud deliberadamente bien formada usando fetch e imprime el objeto de error JSON-RPC sin procesar, incluidos code, message y data. Ejecútalo contra tu endpoint para ver qué devuelve realmente el nodo antes de cualquier abstracción de biblioteca.

Reemplaza la URL del endpoint por la tuya. La solicitud es intencionalmente mínima para que cualquier fallo sea atribuible al nodo o al proveedor, no a la forma de la solicitud.

const endpoint = 'https://your-endpoint.example';

async function probe() {
  const body = {
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_estimateGas',
    params: [{
      from: '0x0000000000000000000000000000000000000000',
      to: '0x0000000000000000000000000000000000000000',
      value: '0x0'
    }]
  };

  const started = Date.now();
  const res = await fetch(endpoint, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(body)
  });
  const elapsed = Date.now() - started;
  const json = await res.json();

  console.log('httpStatus', res.status);
  console.log('elapsedMs', elapsed);
  console.log('error', JSON.stringify(json.error, null, 2));
  console.log('result', json.result);
}

probe().catch((e) => console.error('transport', e));

eth_estimateGas y el patrón de disparo de -32603

Los fallos de estimación son la fuente de producción más común de -32603. Cuando eth_estimateGas no puede determinar un límite de gas, el nodo puede lanzar una excepción interna que se manifiesta como -32603 en lugar de una reversión estructurada. La solución es reproducir la misma llamada como eth_call con un valor de gas explícito, lo que fuerza a la EVM a ejecutar y devolver datos de reversión en lugar de fallar durante la estimación.

Usa los mismos campos from, to, value y data de la estimación fallida. Establece gas a un valor lo suficientemente alto para evitar un out-of-gas durante la reproducción, luego decodifica los datos devueltos. Si la reproducción devuelve un selector de reversión, el fallo es lógica del contrato. Si devuelve -32603 de nuevo, el fallo es más probablemente infraestructura del nodo o del proveedor.

Para fallos relacionados a nivel de transporte, consulta Cómo solucionar errores de timeout de RPC y Cómo solucionar errores RPC 429.

• Los fallos de estimación con frecuencia se manifiestan como -32603 en lugar de una reversión.
• Reproduce como eth_call con gas explícito para forzar la ejecución.
• Decodifica el campo data para distinguir la lógica del contrato de la infraestructura.

Verificación de fallos del lado del proveedor reproduciendo contra un segundo endpoint

Si la solicitud sin procesar falla, reproduce la solicitud idéntica contra un segundo endpoint. Si el segundo endpoint tiene éxito, el fallo es del lado del proveedor o específico de ese nodo. Si ambos fallan de manera idéntica, el fallo probablemente está en la solicitud misma o en la llamada al contrato. Registra los resultados en una tabla para que la comparación sea reproducible.

La siguiente tabla es una plantilla. Complétala con tus propias mediciones. No confíes en cifras publicadas de latencia o tasa de errores de ningún proveedor, incluido OnFinality; mide contra tus propios endpoints.

• Endpoint: la URL que probaste.
• Code: el código de error JSON-RPC devuelto.
• Message: la cadena del mensaje de error.
• Data: cualquier carga útil de data devuelta.
• HTTP status: el código de estado a nivel de transporte.
• Elapsed ms: tiempo de reloj de pared para la solicitud.

Rol del campo data y comportamiento de MetaMask

El campo data es opcional en el objeto de error JSON-RPC 2.0, y su contenido está definido por la implementación. Cuando un nodo incluye una carga útil de reversión en data, puedes decodificarla para identificar la condición del contrato que falla. Cuando data está ausente, el error es opaco y debes confiar en la bisección.

MetaMask y billeteras similares a menudo muestran -32603 sin data porque el proveedor interno de la billetera envuelve la respuesta del nodo y descarta la carga útil. Una llamada directa al nodo puede incluir una carga útil de reversión que la billetera oculta. Este es un comportamiento documentado que varía según la versión de la billetera y el proveedor, así que siempre confirma con una solicitud sin procesar antes de concluir que el nodo no devolvió nada útil.

Para orientación sobre selección de endpoints, consulta la guía de endpoints RPC y precios de RPC.

Modos de fallo comunes y sus soluciones

Varios patrones recurrentes producen -32603. La serialización de cantidades hexadecimales es un culpable frecuente: valores como gas o value deben ser cadenas codificadas en hexadecimal, no números decimales. Un resultado null convertido en un error lanzado por una biblioteca de cliente es otro: algunas bibliotecas tratan un resultado null como un error incluso cuando el nodo devolvió una respuesta válida. Un proxy ascendente que muestra incorrectamente un fallo de límite de tasa o autenticación como -32603 es un tercer patrón, a menudo visible solo al comparar códigos de estado HTTP entre endpoints.

Las solicitudes por lotes añaden otra dimensión. En un lote, un elemento puede llevar el error -32603 mientras otros tienen éxito. Inspecciona el objeto de error de cada elemento individualmente en lugar de tratar el lote como un solo fallo. Para detalles específicos de lotes, consulta Mejores prácticas de batching JSON-RPC.

• Serialización de cantidades hexadecimales: asegúrate de que gas, value y nonce sean cadenas hexadecimales.
• Coerción de resultado null: verifica si tu biblioteca lanza errores con resultados null.
• Mala visualización del proxy: compara códigos de estado HTTP entre endpoints.
• Errores de elementos de lote: inspecciona el objeto de error de cada elemento por separado.

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

Trabaja a través de la lista de verificación en orden. Cada paso elimina una capa de abstracción y reduce el dominio del fallo. Detente cuando el error cambie o desaparezca, porque eso identifica la capa que acabas de eliminar.

Si la lista de verificación no resuelve el problema, escala con la solicitud sin procesar, la respuesta sin procesar, la URL del endpoint y la tabla de resultados. Esa evidencia permite a un proveedor u operador de nodo reproducir el fallo sin adivinar.

• Reproduce con curl sin procesar, evitando tu biblioteca de aplicación.
• Verifica que todas las cantidades hexadecimales sean cadenas, no números.
• Reproduce como eth_call con gas explícito y campos de llamada completos.
• Decodifica el campo data si está presente.
• Reproduce contra un segundo endpoint y compara.
• Inspecciona los elementos del lote individualmente.
• Revisa los códigos de estado HTTP para fallos a nivel de proxy.
• Registra los resultados en una tabla antes de escalar.

Limitaciones y compensaciones de ramificar según -32603

-32603 no es lo suficientemente estable para ramificar en la lógica de la aplicación. Debido a que el mismo código puede significar un error del cliente, un pánico del nodo o un fallo de enrutamiento del proveedor, tratarlo como una señal de lógica de negocio producirá un comportamiento incorrecto. El patrón recomendado es reintentar una vez, luego exponer el error para depuración humana en lugar de intentar una recuperación automatizada.

Esta limitación es inherente al diseño de la especificación. El rango reservado existe para dar a los servidores una salida genérica, no para proporcionar diagnósticos precisos. Las aplicaciones que necesitan un manejo preciso de errores deben confiar en datos de error específicos del método cuando estén disponibles, y tratar -32603 como un fallo desconocido.

Para patrones relacionados de manejo de errores, consulta Cómo solucionar errores RPC 429 y Cómo solucionar errores de timeout de RPC.

• No ramifiques según -32603 para lógica de negocio.
• Reintenta una vez, luego expón para depuración humana.
• Prefiere datos de error específicos del método cuando estén disponibles.
• Trata -32603 como un fallo desconocido por defecto.

Próximos pasos para un manejo confiable de errores RPC

Después de aislar un fallo -32603, el siguiente paso es reforzar tu ruta de solicitud. Valida la serialización hexadecimal antes de enviar, registra las respuestas sin procesar junto con los errores a nivel de biblioteca y mantén un segundo endpoint para comparación. Estas prácticas reducen el tiempo para diagnosticar futuros errores internos.

Para cargas de trabajo en producción, considera un proveedor que exponga respuestas JSON-RPC sin procesar sin envolver. Explora endpoints de Ethereum, revisa las opciones de servicio API y consulta precios de RPC para que coincidan con tus requisitos de manejo de errores. El centro de aprendizaje de OnFinality recopila guías relacionadas de solución de problemas.

• Valida la serialización hexadecimal antes de enviar solicitudes.
• Registra las respuestas sin procesar junto con los errores de la biblioteca.
• Mantén un segundo endpoint para comparación.
• Elige un proveedor que exponga respuestas JSON-RPC sin procesar.