Método RPC no encontrado (-32601): espacios de nombres y capacidades del endpoint

El código de error -32601 en la especificación JSON-RPC 2.0

La especificación JSON-RPC 2.0 define un pequeño conjunto de códigos de error predefinidos en la Sección 5.1. El código -32601 está reservado para "Método no encontrado" y se devuelve cuando el método solicitado no existe o no está disponible. Esa única frase encierra las dos causas que encontrarás en RPC de blockchain: el nombre del método puede ser desconocido para el servidor, o el método puede existir en el software del servidor pero no estar disponible para tu solicitud.

La especificación no exige que el servidor explique cuál de esas dos situaciones aplica. El objeto de error puede incluir un campo data con detalle adicional, pero muchas implementaciones devuelven solo el código y un mensaje corto. Por eso la misma llamada puede funcionar en un endpoint y fallar con -32601 en otro: el código describe la respuesta del endpoint, no la validez de la lógica de tu aplicación.

La especificación JSON-RPC de Ethereum se basa en esta base agrupando métodos en espacios de nombres como eth, net, web3, debug, trace, txpool y admin, con espacios de nombres adicionales en algunos clientes L2 y derivados de Parity. La pertenencia a un espacio de nombres es una convención, no una garantía de exposición. Un endpoint puede implementar completamente el espacio de nombres eth y devolver -32601 para cada llamada debug y trace.

• Fuente autorizada: especificación JSON-RPC 2.0, Sección 5.1 (objeto de error y códigos predefinidos).
• Fuente autorizada: especificación JSON-RPC de Ethereum (espacios de nombres y definiciones de métodos).
• -32601 significa "no encontrado o no disponible" — no distingue entre ambos casos.

Dos causas distintas que se manifiestan como -32601

La primera causa es un nombre de método genuinamente desconocido. Esto incluye errores tipográficos y de mayúsculas/minúsculas, llamar a un método que pertenece al dialecto de otra cadena, o llamar a un método que solo existe en una bifurcación específica de un cliente. Por ejemplo, un método añadido por un cliente de ejecución puede no existir en otro, y una L2 puede exponer un espacio de nombres que la L1 no. Si el nombre es incorrecto, ninguna configuración del endpoint lo solucionará.

La segunda causa es un método que existe en el software del cliente pero que el endpoint deliberadamente no expone. Los operadores deshabilitan espacios de nombres por razones de costo, seguridad y estabilidad. Una llamada debug o trace puede ser órdenes de magnitud más costosa que una simple lectura, y los métodos admin pueden cambiar el estado del nodo. Cuando un espacio de nombres está deshabilitado a nivel de puerta de enlace o de configuración del nodo, el método es efectivamente invisible y el servidor devuelve correctamente -32601.

Distinguir ambas causas importa porque las soluciones son diferentes. Un error tipográfico se corrige en tu código. Un espacio de nombres deshabilitado se soluciona cambiando de endpoint, cambiando el tipo de nodo o cambiando el método que llamas. Tratar -32601 como un error de código cuando es una declaración de capacidad conduce a perder tiempo depurando.

• Nombre desconocido: error tipográfico, mayúsculas/minúsculas incorrectas, dialecto de cadena incorrecto, método exclusivo de una bifurcación de cliente.
• Método no disponible: espacio de nombres deshabilitado, nodo no de archivo, restricción por plan del proveedor.
• El payload del error por sí solo a menudo no puede decirte qué causa aplica — sondea para averiguarlo.

Por qué los endpoints compartidos y públicos deshabilitan debug, trace, admin y txpool

Los endpoints públicos y compartidos suelen deshabilitar los espacios de nombres debug, trace, admin y txpool. Las razones están documentadas y son consistentes entre proveedores: las llamadas trace y debug pueden consumir grandes cantidades de CPU y memoria por solicitud, los métodos admin pueden alterar el comportamiento del nodo, y la inspección de txpool expone datos del mempool que los operadores pueden no querer publicar. Deshabilitar estos espacios de nombres protege el endpoint para todos los usuarios.

Exactamente qué espacios de nombres expone cada proveedor está documentado por proveedor y varía según el proveedor, el plan e incluso la región. No existe una tabla universal. Un proveedor puede habilitar trace en un nivel de pago y deshabilitarlo en un nivel gratuito, o habilitar txpool en una cadena y no en otra. Por eso la habilidad práctica no es memorizar una tabla sino descubrir la capacidad de forma programática.

Para una orientación más amplia sobre la selección de endpoints y qué esperar del RPC gestionado, consulta la guía de endpoints RPC (RPC Assistant). Si tu carga de trabajo depende específicamente de trace y debug, el artículo sobre espacios de nombres trace y debug de Ethereum cubre esos métodos en profundidad, y el artículo sobre el espacio de nombres txpool de Ethereum cubre la inspección del mempool.

• Costo: las llamadas trace y debug son costosas por solicitud.
• Seguridad: los métodos admin pueden cambiar el estado del nodo; txpool expone datos del mempool.
• Estabilidad: deshabilitar espacios de nombres pesados protege la capacidad compartida.
• La exposición está documentada por proveedor y varía según proveedor, plan y cadena.

Una sonda de capacidades que se ejecuta al inicio de la aplicación

Como no existe una llamada estandarizada de descubrimiento de capacidades en JSON-RPC, el enfoque fiable es sondear. Una sonda es un pequeño conjunto de llamadas baratas, una por cada espacio de nombres del que depende tu aplicación, ejecutadas al inicio. Primero demuestra conectividad con un método de bajo costo como eth_chainId o net_version. Luego intenta un método representativo de cada espacio de nombres que necesites y registra el resultado.

El ejemplo siguiente usa Node.js con la API fetch integrada, por lo que no tiene dependencias. Llama a eth_chainId para confirmar que el endpoint es accesible, luego sondea eth, net, web3, debug, trace, txpool y admin con un método cada uno. Registra el código y el mensaje de cada intento e imprime un resumen. Ejecútalo contra cada endpoint que estés considerando y compara la salida.

Mantén la lista de sondas pequeña y barata. No sondees con métodos costosos como debug_traceTransaction en un endpoint de producción a alta frecuencia. Una sola llamada por espacio de nombres al inicio es suficiente para saber si el espacio de nombres está presente.

// capability-probe.js — Node.js 18+ (built-in fetch, no dependencies)
const ENDPOINT = process.env.RPC_URL || "https://your-endpoint.example";

// One cheap, representative method per namespace.
const PROBES = [
  { ns: "eth",    method: "eth_chainId",            params: [] },
  { ns: "net",    method: "net_version",           params: [] },
  { ns: "web3",   method: "web3_clientVersion",    params: [] },
  { ns: "debug",  method: "debug_traceTransaction", params: ["0x" + "00".repeat(32)] },
  { ns: "trace",  method: "trace_block",           params: ["latest"] },
  { ns: "txpool", method: "txpool_status",         params: [] },
  { ns: "admin",  method: "admin_peers",           params: [] }
];

async function call(method, params) {
  const body = { jsonrpc: "2.0", id: 1, method, params };
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body)
  });
  const json = await res.json();
  return { http: res.status, json };
}

(async () => {
  // Step 1: prove connectivity with a low-cost call.
  const ping = await call("eth_chainId", []);
  if (ping.json.error) {
    console.error("Endpoint unreachable or rejecting requests:", ping.json.error);
    process.exit(1);
  }
  console.log("Connected. chainId =", ping.json.result);

  // Step 2: probe each namespace and record the outcome.
  const rows = [];
  for (const p of PROBES) {
    try {
      const { http, json } = await call(p.method, p.params);
      const err = json.error;
      rows.push({
        namespace: p.ns,
        method: p.method,
        http,
        code: err ? err.code : "ok",
        message: err ? err.message : "success",
        enabled: err ? "n" : "y"
      });
    } catch (e) {
      rows.push({
        namespace: p.ns,
        method: p.method,
        http: "network-error",
        code: "-",
        message: String(e),
        enabled: "?"
      });
    }
  }

  console.table(rows);
  const missing = rows.filter(r => r.code === -32601).map(r => r.namespace);
  if (missing.length) {
    console.warn("Namespaces returning -32601:", missing.join(", "));
  }
})();

Metadatos estáticos de capacidades frente a sondeo

Algunos proveedores publican metadatos estáticos de capacidades: una tabla de documentación, un endpoint de capacidades o un manifiesto legible por máquina que lista los espacios de nombres admitidos por cadena. Cuando existe, es un punto de partida útil. Pero la exposición cambia sin previo aviso. Un proveedor puede habilitar un espacio de nombres, deshabilitarlo durante un incidente o moverlo detrás de un nivel de plan. Una tabla de documentación que era precisa el trimestre pasado puede estar equivocada hoy.

El sondeo es más fiable porque mide el endpoint que realmente estás usando, en el momento en que lo usas. La contrapartida es que una lista de sondas debe mantenerse a mano a medida que las cadenas añaden espacios de nombres. No existe una llamada estandarizada de descubrimiento de capacidades en JSON-RPC, por lo que tu lista de sondas es un artefacto vivo. Trata los metadatos estáticos como documentación y el sondeo como verificación.

Un patrón práctico es combinar ambos: lee las capacidades documentadas del proveedor para construir tu lista inicial de sondas, luego ejecuta la sonda al inicio y registra el resultado. Si la sonda contradice la documentación, confía en la sonda y reporta la discrepancia al proveedor.

• Metadatos estáticos: rápidos de leer, pero pueden estar desactualizados o ser específicos de un plan.
• Sondeo: autoritativo para el endpoint que tienes delante, pero requiere mantenimiento.
• Combínalos: documenta para planificar, sondea para verificar.

Disponibilidad de espacios de nombres, tipo de nodo y requisitos de archivo

La disponibilidad de espacios de nombres no es la única puerta. El tipo de nodo también importa. Los métodos de estado histórico, como eth_getBalance en un bloque antiguo o debug_traceTransaction sobre bloques históricos, requieren un nodo de archivo incluso cuando el espacio de nombres está habilitado. Un nodo completo poda el estado antiguo, por lo que el método puede existir y el espacio de nombres puede estar activo, pero la llamada falla porque el bloque solicitado ya no está disponible.

Esto produce un error diferente a -32601 en muchos casos, a menudo un mensaje de nodo de trie faltante o estado no disponible. Pero la lección práctica es la misma: un sondeo exitoso de un espacio de nombres no garantiza que todos los métodos de ese espacio de nombres funcionen para todas las alturas de bloque. Si tu aplicación necesita estado histórico, confirma la disponibilidad de archivo por separado de la disponibilidad del espacio de nombres.

Para cadenas basadas en Substrate, los metadatos del runtime y el versionado añaden otra dimensión; el artículo sobre state_getMetadata de Substrate y versiones del runtime cubre cómo se comportan las llamadas de metadatos a través de actualizaciones del runtime. El principio se generaliza: la capacidad tiene capas — espacio de nombres, tipo de nodo y estado de la cadena.

• Espacio de nombres habilitado + nodo completo = los métodos de estado histórico aún pueden fallar.
• Espacio de nombres habilitado + nodo de archivo = los métodos de estado histórico tienen más probabilidades de funcionar.
• Sondea el espacio de nombres, luego verifica el comportamiento de archivo con una llamada a un bloque histórico.

Restricciones de transporte: HTTP frente a suscripciones WebSocket

El transporte es otra capa de capacidad. Los métodos de suscripción como eth_subscribe y eth_unsubscribe son solo WebSocket en las implementaciones comunes de JSON-RPC de Ethereum. Si envías eth_subscribe por HTTP, el endpoint puede devolver -32601 aunque el espacio de nombres eth esté completamente habilitado. El método no está disponible porque el espacio de nombres esté apagado; está disponible solo a través de ese transporte.

Esta es una fuente frecuente de confusión porque el mismo endpoint puede servir tanto HTTP como WebSocket en URLs diferentes. Si tu sonda se ejecuta por HTTP e informa que eth está habilitado, eso no te dice si las suscripciones funcionan. Sondea las suscripciones específicamente por el transporte WebSocket, o consulta la documentación del proveedor para la URL de suscripción.

La regla general: una sonda de capacidades debe usar el mismo transporte que usará tu aplicación. Una sonda HTTP valida métodos HTTP. Una sonda WebSocket valida suscripciones. No infieras una de la otra.

• eth_subscribe y eth_unsubscribe son comúnmente solo WebSocket.
• HTTP puede devolver -32601 para un método de suscripción incluso cuando eth está habilitado.
• Sondea por el transporte que realmente usarás en producción.

Tabla de resultados por espacio de nombres para tus propios endpoints

Usa la tabla siguiente para registrar lo que realmente admite cada uno de tus endpoints. Complétala ejecutando la sonda de la sección anterior contra cada endpoint y copiando el código y el mensaje en la tabla. Mantén una tabla por entorno (desarrollo, staging, producción) porque la exposición puede diferir según el plan y la región.

La columna "habilitado" es tu conclusión, no el código sin procesar. Un -32601 significa no habilitado para ese método a través de ese transporte. Un éxito significa habilitado. Un error de red significa desconocido — reintenta antes de concluir. La columna de notas es donde registras contexto como "requiere archivo" o "solo WebSocket".

• Espacio de nombres | Método | Código | Mensaje | Habilitado (s/n) | Nota
• eth | eth_chainId | | | |
• net | net_version | | | |
• web3 | web3_clientVersion | | | |
• debug | debug_traceTransaction | | | | requiere archivo para bloques históricos
• trace | trace_block | | | |
• txpool | txpool_status | | | |
• admin | admin_peers | | | |
• eth (ws) | eth_subscribe | | | | solo transporte WebSocket

Guía de decisión: cambiar método, cambiar endpoint o cambiar tipo de nodo

Una vez que tengas los resultados de la sonda, la decisión suele ser sencilla. Si el nombre del método es incorrecto — un error tipográfico, mayúsculas/minúsculas incorrectas o un método del dialecto de otra cadena — cambia el método. Verifica el nombre exacto contra la especificación JSON-RPC de Ethereum o la documentación de la cadena relevante antes de asumir que el endpoint tiene la culpa.

Si el nombre del método es correcto y el espacio de nombres devuelve -32601, cambia el endpoint. Elige un proveedor o plan que documente el espacio de nombres que necesitas. Para endpoints de Ethereum mainnet, la página networks/eth lista las redes disponibles, y precios de RPC describe cómo se relacionan los niveles de plan con el acceso a espacios de nombres. Si estás construyendo un servicio que necesita acceso garantizado a espacios de nombres, la página de servicio de API describe las opciones de acceso gestionado.

Si el espacio de nombres está habilitado pero las llamadas históricas fallan, cambia el tipo de nodo a un nodo de archivo. Si las suscripciones fallan por HTTP, cambia el transporte a WebSocket. Cada una de estas es una solución diferente para una capa diferente de la pila de capacidades.

• Nombre de método incorrecto → corrige el método en tu código.
• Nombre correcto, -32601 → cambia de endpoint o plan.
• Espacio de nombres activo, llamada histórica falla → cambia a nodo de archivo.
• Suscripción falla por HTTP → cambia el transporte a WebSocket.

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

Recorre esta lista en orden. Va de las comprobaciones más baratas a las más costosas, para que evites cambiar infraestructura por un problema que se resolvería con un cambio de un carácter.

Si ninguna de estas resuelve el error, el endpoint realmente no expone el espacio de nombres. En ese punto aplica la guía de decisión anterior. Para un recorrido más amplio sobre selección de endpoints y problemas comunes de integración, el centro de aprendizaje de OnFinality recopila guías relacionadas, y el artículo sobre migración de métodos RPC obsoletos de Solana muestra cómo se desarrolla en la práctica la eliminación de un método específico.

• Compara el nombre del método carácter por carácter contra la especificación, incluyendo mayúsculas/minúsculas.
• Confirma que no estás llamando a un método de suscripción por HTTP.
• Comprueba si un proxy, balanceador de carga o puerta de enlace está eliminando o reescribiendo la ruta de la solicitud.
• Reintenta una vez para descartar un 404 de enrutamiento transitorio que se manifestó como error JSON-RPC.
• Verifica que la URL del endpoint apunta a la cadena que pretendes, no a una testnet u otra red.
• Ejecuta la sonda de capacidades y registra el código y el mensaje exactos.
• Si el espacio de nombres está habilitado, prueba un bloque histórico para comprobar la disponibilidad de archivo.

Limitaciones y contrapartidas del descubrimiento de capacidades

No existe una llamada estandarizada de descubrimiento de capacidades en JSON-RPC. La especificación define códigos de error y semántica de métodos, pero no define un método que liste los métodos admitidos. Esto significa que toda sonda de capacidades es una lista mantenida a mano. A medida que las cadenas añaden espacios de nombres — por ejemplo, nuevos espacios de nombres específicos de L2 o métodos de bifurcaciones de clientes — tu lista de sondas debe actualizarse para cubrirlos.

Un proveedor también puede devolver -32601 para un método que pretende añadir más adelante. El método no está disponible hoy, pero la ausencia es un estado de hoja de ruta más que una limitación permanente. El sondeo te dice la verdad actual; no te dice los planes del proveedor. Para planificar, combina los resultados de la sonda con la hoja de ruta publicada o el canal de soporte del proveedor.

Por último, el sondeo añade latencia de inicio y un pequeño número de solicitudes. Para la mayoría de las aplicaciones esto es insignificante, pero para servicios sensibles a la latencia quizá quieras almacenar en caché los resultados de la sonda y actualizarlos periódicamente en lugar de en cada inicio de proceso. La contrapartida está entre la frescura y el costo de inicio.

• No existe una llamada estandarizada de descubrimiento de capacidades en JSON-RPC.
• Las listas de sondas deben mantenerse a mano a medida que las cadenas añaden espacios de nombres.
• -32601 puede indicar un método que el proveedor planea añadir más adelante.
• Almacena en caché los resultados de la sonda si la latencia de inicio importa.

Próximos pasos para una integración fiable de espacios de nombres

Empieza ejecutando la sonda de capacidades contra cada endpoint de tu entorno y completando la tabla de resultados. Ese único ejercicio convierte las conjeturas en un mapa de capacidades documentado. Luego codifica los resultados en las comprobaciones de inicio de tu aplicación para que un espacio de nombres faltante falle rápido con un mensaje claro en lugar de manifestarse como un misterioso -32601 en lo profundo de un manejador de solicitudes.

Si tu carga de trabajo depende de trace, debug o txpool, revisa los artículos dedicados sobre los espacios de nombres trace y debug de Ethereum y el espacio de nombres txpool de Ethereum para entender el costo y las características de datos de esos métodos. Si aún estás eligiendo un endpoint, las páginas de guía de endpoints RPC (RPC Assistant) y precios de RPC te ayudan a emparejar los niveles de plan con los requisitos de espacios de nombres.

El hábito duradero es simple: nunca asumas que un espacio de nombres está disponible. Sondéalo, regístralo y vuelve a sondearlo cuando cambies de endpoint o de plan. Ese hábito convierte -32601 de un fallo confuso en una señal clara y accionable sobre la capacidad del endpoint.

• Ejecuta la sonda contra cada endpoint y registra los resultados.
• Añade comprobaciones de inicio que fallen rápido ante espacios de nombres faltantes.
• Vuelve a sondear después de cualquier cambio de endpoint o plan.
• Usa el centro de aprendizaje de OnFinality para guías de integración relacionadas.