Errores de transacción en Ethereum explicados: qué significa cada mensaje y cómo arreglarlo

1. ¿De dónde salen estos mensajes de error?

Casi todas las wallets, librerías y proveedores RPC pasan tal cual el texto de error que produce go-ethereum, el cliente de Ethereum más extendido, y los clientes de las redes Layer 2 reutilizan las mismas cadenas de texto. MetaMask las envuelve en su propio diálogo, ethers.js añade un código como NONCE_EXPIRED o REPLACEMENT_UNDERPRICED, y un proveedor RPC las devuelve como un error JSON-RPC con código -32000. Por debajo, el mensaje es el mismo.

El nodo ejecuta dos conjuntos de comprobaciones distintos. El primero ocurre cuando recibe la transacción: si el nonce es correcto, si la fee es aceptable, si el gas limit es razonable, si el remitente puede pagar. Una transacción que falla aquí se descarta y no queda nada registrado on-chain. El segundo ocurre cuando la transacción se ejecuta dentro de un bloque: si el código del contrato termina dentro del gas limit sin revertir. Una transacción que falla aquí se mina de todos modos, con estado Fail en el explorador, y la fee se gasta.

Saber a qué familia pertenece un error te dice dos cosas a la vez: si has perdido dinero, y si la solución está de tu lado (la transacción) o del lado del contrato (los parámetros de entrada).

2. Referencia rápida: todos los errores habituales

Las cadenas de texto exactas, en el orden en que es más probable que te las encuentres. La redacción es la del código fuente de go-ethereum; las wallets a veces la acortan.

3. ¿Qué significa "nonce too low"?

Cada cuenta numera sus transacciones desde cero, y cada número solo puede usarse una vez. "Nonce too low" significa que la transacción que acabas de enviar lleva un número que la red ya ha confirmado para esa cuenta. El nodo compara el nonce de tu transacción con el siguiente nonce esperado de la cuenta y rechaza cualquiera que quede por debajo.

Ocurre cuando la idea que tiene la wallet del siguiente nonce está desactualizada: se envió una transacción desde la misma cuenta en otra wallet u otro dispositivo, una aceleración o cancelación ya ocupó ese número, o se reinició una cadena de desarrollo local y el contador de la cuenta volvió a cero mientras MetaMask seguía contando. En una hardware wallet también aparece cuando una transacción se firma dos veces.

La solución es dejar que la wallet se resincronice. Busca primero la dirección en el explorador: si lo que intentabas hacer ya salió con ese nonce, no lo reenvíes. Si la wallet sigue proponiendo un número desactualizado, la opción de MetaMask "Delete activity and nonce data" (eliminar datos de actividad y nonce), en Configuración, Herramientas de desarrollo, borra el contador local de la red actual. MetaMask advierte que es irreversible, que afecta solo a la red actual y que no toca tu saldo. En código, lee el siguiente nonce con eth_getTransactionCount usando la etiqueta "pending" antes de firmar, en lugar de llevar tu propio contador.

4. ¿Qué significa "nonce too high"?

El desfase contrario. El nonce de la transacción está por encima del siguiente valor esperado de la cuenta, así que hay un hueco: un número inferior aún no se ha confirmado. Los nodos guardan esa transacción en una cola en lugar de ejecutarla, y algunos la rechazan directamente con este mensaje.

Causa típica: un lote de transacciones en el que una anterior se descartó, o un reinicio de cadena local en el sentido contrario (se reinició la cadena pero no la wallet, así que la wallet envía el nonce 40 a una cadena que espera el nonce 0). Rellena el hueco enviando el nonce que falta, o borra los datos de actividad de la wallet como se explica arriba.

5. ¿Qué significa "replacement transaction underpriced"?

Intentaste reemplazar una transacción pendiente (acelerarla, cancelarla o simplemente reenviarla con el mismo nonce) y la nueva no paga suficiente más que la antigua. El nodo solo cambia una transacción pendiente por otra con el mismo nonce si la fee sube un porcentaje mínimo; en go-ethereum ese incremento de precio es del 10 por ciento por defecto, y se aplica tanto a la max fee como a la priority fee.

El nonce es correcto; el problema es el precio. Sube los dos campos de fee al menos un 10 por ciento respecto a la transacción pendiente, no respecto a la tarifa actual de la red. La propia guía de MetaMask para el diálogo relacionado de "transaction underpriced" recomienda una priority fee al menos un 10 por ciento más alta y una max fee al menos un 30 por ciento más alta. Para cancelar en su lugar, envía 0 ETH a tu propia dirección con el mismo nonce y la fee subida, como se describe en la guía de errores de MetaMask. En ambos casos el reemplazo recibe un hash de transacción nuevo y la antigua se descarta.

6. ¿Qué significa "transaction underpriced"?

Sin la palabra "replacement", esto es una simple comprobación de precio: la fee de tu transacción está por debajo de lo que el nodo está dispuesto a mantener en su pool. Los nodos fijan un precio de gas mínimo para mantener fuera el spam, y en un periodo de congestión la estimación de fee "baja" de una wallet puede quedar por debajo. El mensaje hermano "transaction gas price below minimum" significa lo mismo.

Sube la max fee y la priority fee y reenvía. No quedó nada registrado on-chain, así que no hay ninguna transacción atascada que limpiar. Si te sale repetidamente en una red, el mínimo de esa red es más alto que el valor por defecto de tu wallet; las páginas por red del gas tracker muestran la tarifa vigente.

7. ¿Qué significa "insufficient funds for gas * price + value"?

El saldo del remitente en la moneda nativa tiene que cubrir el importe que se envía más la fee en el peor caso, que es el gas limit multiplicado por la max fee per gas. Esa regla está escrita en EIP-1559: quien firma tiene que poder pagar gas_limit por max_fee_per_gas, además del valor. El nodo lo comprueba contra el máximo, no contra lo que la transacción costará en realidad, así que una transacción puede fallar esta comprobación aunque la fee final hubiera cabido.

Tres causas cubren casi todos los casos. Tienes tokens pero no moneda nativa: USDC en Base necesita ETH para el gas, USDT en Polygon necesita POL, cualquier cosa en BNB Smart Chain necesita BNB. Estás enviando todo tu saldo y no has dejado nada para la fee: resta primero la fee máxima. O el gas limit está inflado por una llamada a contrato, así que el peor caso queda muy por encima del coste real.

Solución: recarga la moneda nativa, envía un importe menor, o baja la max fee o el gas limit si tienen margen de sobra. El mensaje relacionado "insufficient funds for transfer" significa que el valor por sí solo supera el saldo, antes siquiera de considerar el gas.

8. Intrinsic gas too low, out of gas y errores de gas limit

Cuatro mensajes tienen que ver con el gas limit, y fallan en momentos distintos. "Intrinsic gas too low" es un rechazo previo a la inclusión: toda transacción tiene un coste base fijo antes de que se ejecute ningún código, 21.000 gas para una transferencia simple más un cargo por cada byte de datos, y tu gas limit está por debajo. La documentación sobre gas de ethereum.org sitúa la transferencia estándar en 21.000 unidades; una transferencia de tokens o una llamada a contrato necesita más. Sube el límite, o deja que la wallet o la librería lo estimen.

"Out of gas" es la versión posterior a la inclusión. El límite cubría el coste base, la transacción se minó, y después el código del contrato necesitó más de lo que el límite permitía. El EVM revierte todos los cambios de estado pero, como dice la misma documentación, todo el gas aportado se consume igualmente por el trabajo realizado. La fee se pierde y la transacción aparece como fallida en el explorador. Reenvía con un límite más alto; las wallets suelen añadir un margen sobre la estimación precisamente por esto.

"Exceeds block gas limit" significa que el límite que fijaste es mayor de lo que puede contener un bloque entero en esa red. "Transaction gas limit too high" es más reciente: desde EIP-7825 una sola transacción no puede pedir más de 16.777.216 gas (2 elevado a 24), y una transacción por encima del tope se rechaza. Ambos se arreglan bajando el límite; una transacción legítima nunca necesita nada que se acerque a esas cifras.

9. Errores de max fee y priority fee

Desde EIP-1559 una transacción lleva dos campos de fee: la max fee per gas, que es lo máximo que pagarás por unidad, y la max priority fee per gas, la propina para el validador. El protocolo impone dos relaciones entre ellas y la base fee del bloque, y cada una tiene su propio error.

"Max fee per gas less than block base fee": tu max fee está por debajo de la base fee actual, así que la transacción no puede incluirse con ninguna propina. Afecta a transacciones firmadas en un periodo tranquilo y emitidas después de que subiera la base fee, y a transacciones construidas con una fee fija en el código. Sube la max fee, o espera: la base fee se mueve bloque a bloque y la transacción vuelve a ser válida si cae por debajo de tu tope.

"Max priority fee per gas higher than max fee per gas": la propina supera el tope total, lo que la especificación prohíbe porque la base fee se cubre primero y la propina solo puede salir de lo que queda. Pon la priority fee igual o por debajo de la max fee. Una transacción bien construida tiene una max fee de aproximadamente el doble de la base fee más la propina, lo que deja margen para que la base fee suba mientras espera.

10. ¿Qué significa "execution reverted"?

El contrato al que llamaste detuvo la ejecución a propósito. Las sentencias require, revert y assert de Solidity terminan todas en este mensaje, a menudo seguido de la cadena de motivo propia del contrato: "ERC20: transfer amount exceeds allowance", "UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT", "Pausable: paused", etcétera. Cuando el motivo está vacío, solo ves "execution reverted" o los datos de error en bruto.

La mayoría de las veces lo ves antes de enviar, porque la wallet pasa la llamada por eth_estimateGas y la simulación revierte; MetaMask informa entonces de que no puede estimar el gas. Esa es la versión barata: no se envió nada. La versión cara es una transacción que pasó la simulación, se minó y revirtió on-chain porque el estado cambió entre medias (el precio de un swap se movió más allá de tu slippage, otra persona compró la última unidad, venció un deadline). Aparece como Fail en el explorador y la fee se paga.

La solución nunca es un gas limit más alto. Lee la cadena de motivo y cambia los parámetros de entrada: aprueba el token primero, amplía el slippage o reduce el importe, comprueba que el contrato no está pausado y confirma que estás en la red donde vive el contrato. La página de la transacción en el explorador muestra el motivo del revert en los fallos minados; la guía de Etherscan enseña dónde encontrarlo.

11. Already known, invalid sender y oversized data

"Already known" no es un error en ningún sentido práctico. El nodo ya tiene exactamente la transacción que enviaste, normalmente porque una librería reintentó el envío o dos wallets empujaron los mismos bytes firmados. Espera a que se confirme la original.

"Invalid sender" significa que el nodo no pudo recuperar un firmante válido a partir de la firma. Desde EIP-155 el ID de cadena forma parte de lo que se firma, así que una transacción firmada para la cadena 1 y enviada a la cadena 137 recupera basura y se rechaza. Compara el ID de cadena de la configuración de firma con el que reporta el endpoint RPC; la lista de ID de cadena cubre los números y el caso de la discrepancia.

"Oversized data" significa que el tamaño en bytes de la transacción supera lo que el nodo acepta en su pool, algo que solo ocurre con despliegues de contratos o calldata muy grandes. Divide los datos, o despliega a través de una factory.

12. ¿Cuesta gas una transacción fallida?

Depende de dónde haya fallado. Todo lo que está en la primera familia de esta guía (nonce, underpriced, insufficient funds, intrinsic gas, tope de fee, already known, invalid sender, oversized data) es un rechazo: el nodo descartó la transacción y ningún bloque la contiene, así que no se cobró ninguna fee y no hay nada que encontrar en el explorador. Reenviar no cuesta nada extra.

"Out of gas" y un "execution reverted" minado son la segunda familia: la transacción está en un bloque con estado Fail, el validador hizo el trabajo y la fee se paga entera. La documentación de ethereum.org es explícita en que la fee se paga con independencia de si la transacción tiene éxito o falla. Los ETH o tokens que intentabas mover se quedan donde estaban; solo se pierde la fee.

13. Cómo evitar estos errores en código

Cuatro hábitos eliminan la mayor parte de esta lista de un servicio de envío: leer el nonce pendiente del nodo en lugar de llevar un contador, tomar las estimaciones de fee del nodo de la red en la que estás, estimar el gas antes de firmar y añadir un margen, y comprobar el saldo contra el importe más la fee en el peor caso antes de emitir. El SDK de ChainGate hace las cuatro cosas dentro de transfer(), y expone como error tipado el único caso que tienes que gestionar tú:

import { ChainGate, importWallet, NotEnoughFundsError } from 'chaingate';

const cg = new ChainGate({ apiKey: process.env.CHAINGATE_API_KEY });
const wallet = importWallet({ phrase: process.env.MNEMONIC });
const eth = cg.connect(cg.networks.ethereum, wallet);

try {
  // Nonce, gas limit and EIP-1559 fees are read from the node for you
  const tx = await eth.transfer(cg.networks.ethereum.amount('0.05'), '0x...');
  tx.setFee(tx.recommendedFees().normal);

  if (!tx.enoughFunds()) {
    // amount + worst-case fee exceeds the balance: nothing is broadcast
    console.log('short by', tx.missingFunds());
    return;
  }

  const sent = await tx.signAndBroadcast();
  console.log(sent.transactionId);
} catch (err) {
  if (err instanceof NotEnoughFundsError) {
    console.error('Not enough ETH for amount + fee');
  }
  throw err;
}

El tutorial para enviar cripto en JavaScript muestra el flujo completo para Ethereum y las cadenas UTXO, y la documentación de transfer lista los niveles de fee y el campo missingFunds, que te dice exactamente cuánta moneda nativa falta.

14. Por dónde seguir

La mayoría de estos errores tienen que ver con las fees, así que la siguiente página que leer es qué son las gas fees y cómo encajan max fee, priority fee y base fee, seguida del gas tracker para ver las tarifas de cada red ahora mismo. Si una transacción sí llegó a salir y necesitas averiguar qué pasó con ella, la guía sobre el hash de transacción enseña cómo buscarla. Y para una librería TypeScript que gestiona nonces, fees y comprobaciones de saldo en Ethereum, las Layer 2 EVM y Bitcoin, ChainGate es el SDK detrás de este sitio.

Preguntas frecuentes