Um erro de transação no Ethereum é o motivo que o nó dá para recusar ou falhar a sua transação. "Nonce too low" significa que aquele número de transação já foi usado, então atualize a carteira. "Replacement transaction underpriced" significa que a sua aceleração ou cancelamento não subiu a taxa o suficiente, então aumente-a em pelo menos 10 por cento. "Intrinsic gas too low" significa que o gas limit está abaixo do custo base da transação, então suba-o (21.000 é o mínimo para uma transferência simples). "Insufficient funds for gas * price + value" significa que a conta não cobre o valor mais a taxa máxima, então acrescente moeda nativa. "Execution reverted" significa que o contrato recusou a chamada, o que é um problema de parâmetros, não de taxa.
Nenhuma das rejeições custa gas, porque a transação nunca chegou a um bloco. As duas que custam gas são "out of gas" e "execution reverted" em uma transação que foi minerada: a rede fez o trabalho, o trabalho falhou e a taxa é paga mesmo assim.
As mensagens são curtas, as discussões em fóruns sobre elas são longas, e a maioria termina sem resposta. Este guia pega as strings exatas que o software de nó do Ethereum emite, explica o que cada uma está verificando, diz se a tentativa que falhou custou alguma coisa e dá a correção para quem usa carteira e para quem desenvolve. As mesmas mensagens aparecem na Base, na Arbitrum, na Optimism, na Polygon, na BNB Smart Chain e em todas as outras redes EVM, porque elas compartilham o mesmo código de nó.
A versão curta
- Duas famílias de erro. Rejeições antes de a transação entrar em um bloco (nonce, taxas, fundos, gas limit) não custam nada. Falhas depois da inclusão (out of gas, execution reverted) custam a taxa inteira.
- As strings vêm do go-ethereum: nonce too low · replacement transaction underpriced · intrinsic gas too low · insufficient funds for gas * price + value são verificações sobre a própria transação, não sobre a rede.
- A maioria tem uma correção de uma linha: atualizar a carteira, subir a taxa em pelo menos 10 por cento, acrescentar gas ou repor a moeda nativa.
- Um dapp que falha em "estimate gas" está dizendo que a chamada ao contrato seria revertida. Mude os parâmetros; subir o gas limit não ajuda.
1. De onde vêm essas mensagens de erro?
Quase toda carteira, biblioteca e provedor RPC repassa o texto de erro produzido pelo go-ethereum, o cliente Ethereum mais usado, e os clientes das redes Layer 2 reaproveitam as mesmas strings. A MetaMask as envolve em seu próprio diálogo, o ethers.js acrescenta um código como NONCE_EXPIRED ou REPLACEMENT_UNDERPRICED, e um provedor RPC as devolve como um erro JSON-RPC com código -32000. Por baixo, a mensagem é a mesma.
O nó executa dois conjuntos diferentes de verificações. O primeiro acontece quando ele recebe a transação: o nonce está certo, a taxa é aceitável, o gas limit faz sentido, o remetente consegue pagar. Uma transação que falha aqui é descartada e nada fica registrado on-chain. O segundo acontece quando a transação é executada dentro de um bloco: o código do contrato termina dentro do gas limit sem reverter. Uma transação que falha aqui é minerada mesmo assim, com status Fail no explorer, e a taxa é gasta.
Saber a qual família um erro pertence diz duas coisas de uma vez: se você perdeu dinheiro, e se a correção está do seu lado (a transação) ou do lado do contrato (os parâmetros).
2. Referência rápida: todos os erros comuns
As strings exatas, na ordem em que você tem mais chance de encontrá-las. O texto é o do código-fonte do go-ethereum; as carteiras às vezes o encurtam.
| Mensagem de erro | Significado | Cobra gas? | Correção |
|---|---|---|---|
| nonce too low | Uma transação com este nonce já está confirmada | Não | Atualize a carteira; confira o explorer antes de reenviar |
| nonce too high | Um nonce menor ainda está faltando, então este ainda não pode rodar | Não | Envie ou limpe o nonce que falta; redefina a carteira de desenvolvimento depois de reiniciar uma cadeia local |
| replacement transaction underpriced | Mesmo nonce de uma transação pendente, taxa não subiu o suficiente | Não | Suba os dois campos de taxa em pelo menos 10 por cento |
| transaction underpriced | Taxa abaixo do mínimo do nó | Não | Suba a max fee e a priority fee |
| insufficient funds for gas * price + value | O saldo não cobre o valor mais gas limit vezes max fee | Não | Acrescente moeda nativa (ETH, POL, BNB) ou reduza o valor |
| intrinsic gas too low | Gas limit abaixo do custo base fixo da transação | Não | Suba o gas limit; 21.000 para uma transferência simples |
| exceeds block gas limit / transaction gas limit too high | Gas limit maior do que um bloco permite, ou acima do teto de 16.777.216 | Não | Reduza o gas limit |
| max fee per gas less than block base fee | Sua max fee está abaixo da base fee atual | Não | Suba a max fee ou espere a base fee cair |
| max priority fee per gas higher than max fee per gas | Tip definida acima do teto total da taxa | Não | Defina a priority fee igual ou abaixo da max fee |
| already known | O nó já tem exatamente esta transação | Não | Nada; espere a confirmação |
| invalid sender | A assinatura não pode ser recuperada, normalmente um chain ID incompatível | Não | Assine com o chain ID que o RPC informa |
| execution reverted | O código do contrato recusou a chamada | Só se foi minerada | Corrija os parâmetros: allowance, slippage, saldo, prazo |
| out of gas | A execução passou do gas limit dentro de um bloco | Sim | Reenvie com um gas limit maior |
3. O que significa "nonce too low"?
Toda conta numera suas transações a partir de zero, e cada número pode ser usado uma vez. "Nonce too low" significa que a transação que você acabou de enviar carrega um número que a rede já confirmou para aquela conta. O nó compara o nonce da sua transação com o próximo nonce esperado da conta e recusa qualquer coisa abaixo dele.
Acontece quando a ideia que a carteira tem do próximo nonce está desatualizada: uma transação foi enviada da mesma conta em outra carteira ou outro dispositivo, uma aceleração ou um cancelamento já pegou o número, ou uma cadeia local de desenvolvimento foi reiniciada e o contador da conta voltou a zero enquanto a MetaMask continuou contando. Em uma carteira de hardware também aparece quando uma transação é assinada duas vezes.
A correção é deixar a carteira ressincronizar. Primeiro consulte o endereço no explorer: se o que você estava tentando fazer já passou com aquele nonce, não reenvie. Se a carteira insiste em oferecer um número desatualizado, a opção "Delete activity and nonce data" da MetaMask (apagar dados de atividade e nonce, em Configurações, Ferramentas de desenvolvedor) limpa o contador local da rede atual. A MetaMask avisa que é irreversível, afeta só a rede atual e não mexe no seu saldo. Em código, leia o próximo nonce com eth_getTransactionCount usando a tag "pending" antes de assinar, em vez de manter seu próprio contador.
4. O que significa "nonce too high"?
A lacuna oposta. O nonce da transação está acima do próximo valor esperado da conta, então há um buraco: um número menor ainda não foi confirmado. Os nós mantêm uma transação assim em uma fila em vez de executá-la, e alguns a rejeitam de imediato com esta mensagem.
Causa típica: um lote de transações em que uma anterior foi descartada, ou uma cadeia local redefinida na direção contrária (a cadeia foi redefinida mas a carteira não, então a carteira envia o nonce 40 para uma cadeia que espera o nonce 0). Preencha a lacuna enviando o nonce que falta, ou limpe os dados de atividade da carteira como descrito acima.
5. O que significa "replacement transaction underpriced"?
Você tentou substituir uma transação pendente (acelerar, cancelar ou simplesmente reenviar com o mesmo nonce) e a nova não paga o suficiente a mais do que a antiga. O nó só troca uma transação pendente por outra com o mesmo nonce se a taxa subir uma porcentagem mínima; no go-ethereum esse aumento de preço é de 10 por cento por padrão, e vale tanto para a max fee quanto para a priority fee.
O nonce está certo; o problema é o preço. Suba os dois campos de taxa em pelo menos 10 por cento em relação à transação pendente, não em relação ao preço atual da rede. A orientação da própria MetaMask para o diálogo relacionado "transaction underpriced" é uma priority fee pelo menos 10 por cento maior e uma max fee pelo menos 30 por cento maior. Para cancelar em vez de acelerar, envie 0 ETH para o seu próprio endereço com o mesmo nonce e a taxa aumentada, como descreve o guia de erros da MetaMask. De um jeito ou de outro, a substituta recebe um hash de transação novo e a antiga é descartada.
6. O que significa "transaction underpriced"?
Sem a palavra "replacement", esta é uma verificação simples de preço: a taxa da sua transação está abaixo do que o nó aceita manter no seu pool. Os nós definem um gas price mínimo para barrar spam, e em um período movimentado a estimativa "baixa" da carteira pode ficar abaixo dele. A mensagem irmã "transaction gas price below minimum" significa a mesma coisa.
Suba a max fee e a priority fee e reenvie. Nada foi registrado on-chain, então não há transação presa para limpar. Se isso aparece repetidamente em uma rede, o mínimo daquela rede é maior do que o padrão da sua carteira; as páginas por rede do gas tracker mostram o preço corrente.
7. O que significa "insufficient funds for gas * price + value"?
O saldo do remetente na moeda nativa precisa cobrir o valor enviado mais a taxa no pior caso, que é o gas limit multiplicado pela max fee per gas. Essa regra está escrita na EIP-1559: quem assina precisa conseguir pagar gas_limit vezes max_fee_per_gas, além do valor. O nó verifica isso contra o máximo, não contra o que a transação vai custar de fato, então uma transação pode falhar nessa verificação mesmo que a taxa final coubesse no saldo.
Três causas cobrem quase todos os casos. Você tem tokens mas não tem moeda nativa: USDC na Base precisa de ETH para o gas, USDT na Polygon precisa de POL, qualquer coisa na BNB Smart Chain precisa de BNB. Você está enviando o saldo inteiro e não deixou nada para a taxa: subtraia a taxa máxima primeiro. Ou o gas limit foi inflado por uma chamada a contrato, então o pior caso fica bem acima do custo real.
Correção: reponha a moeda nativa, envie um valor menor, ou reduza a max fee ou o gas limit se estiverem com folga demais. A mensagem relacionada "insufficient funds for transfer" significa que o valor sozinho já excede o saldo, antes mesmo de considerar o gas.
8. Intrinsic gas too low, out of gas e erros de gas limit
Quatro mensagens dizem respeito ao gas limit, e elas falham em momentos diferentes. "Intrinsic gas too low" é uma rejeição antes da inclusão: toda transação tem um custo base fixo antes de qualquer código rodar, 21.000 de gas para uma transferência simples mais uma cobrança por byte de dados, e o seu gas limit está abaixo disso. A documentação sobre gas do ethereum.org coloca a transferência padrão em 21.000 unidades; uma transferência de token ou uma chamada a contrato precisa de mais. Suba o limite, ou deixe a carteira ou a biblioteca estimá-lo.
"Out of gas" é a versão depois da inclusão. O limite cobriu o custo base, a transação foi minerada, e então o código do contrato precisou de mais do que o limite permitia. A EVM reverte toda mudança de estado mas, como diz a mesma documentação, todo o gas fornecido é consumido pelo trabalho realizado. A taxa se foi e a transação aparece como falha no explorer. Reenvie com um limite maior; as carteiras costumam somar uma margem à estimativa justamente por isso.
"Exceeds block gas limit" significa que o limite que você definiu é maior do que um bloco inteiro pode conter naquela rede. "Transaction gas limit too high" é mais recente: desde a EIP-7825 uma única transação não pode pedir mais do que 16.777.216 de gas (2 elevado a 24), e uma transação acima do teto é rejeitada. As duas se corrigem reduzindo o limite; uma transação legítima nunca precisa de nada perto desses números.
9. Erros de max fee e priority fee
Desde a EIP-1559 uma transação carrega dois campos de taxa: a max fee per gas, que é o máximo que você vai pagar por unidade, e a max priority fee per gas, a tip para o validador. O protocolo impõe duas relações entre eles e a base fee do bloco, e cada uma tem seu próprio erro.
"Max fee per gas less than block base fee": a sua max fee está abaixo da base fee atual, então a transação não pode ser incluída com tip nenhuma. Isso atinge transações assinadas em um período calmo e transmitidas depois que a base fee subiu, e transações montadas com uma taxa fixa no código. Suba a max fee, ou espere: a base fee se move bloco a bloco e a transação volta a ser válida se ela cair abaixo do seu teto.
"Max priority fee per gas higher than max fee per gas": a tip excede o teto total, o que a especificação proíbe porque a base fee é preenchida primeiro e a tip só pode sair do que sobra. Defina a priority fee igual ou abaixo da max fee. Uma transação bem montada tem max fee igual a mais ou menos o dobro da base fee mais a tip, o que deixa espaço para a base fee subir enquanto ela espera.
10. O que significa "execution reverted"?
O contrato que você chamou interrompeu a execução de propósito. As instruções require, revert e assert do Solidity terminam todas nesta mensagem, muitas vezes seguida da string de motivo do próprio contrato: "ERC20: transfer amount exceeds allowance", "UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT", "Pausable: paused" e assim por diante. Quando o motivo está vazio, você vê só "execution reverted" ou os dados brutos do erro.
Na maior parte das vezes você vê isso antes de enviar, porque a carteira passa a chamada por eth_estimateGas e a simulação reverte; a MetaMask então informa que não consegue estimar o gas. Essa é a versão barata: nada foi enviado. A versão cara é uma transação que passou na simulação, foi minerada e reverteu on-chain porque o estado mudou no meio do caminho (o preço de um swap passou do seu slippage, outra pessoa comprou o último item, um prazo venceu). Ela aparece como Fail no explorer e a taxa é paga.
A correção nunca é um gas limit maior. Leia a string de motivo e mude os parâmetros: aprove o token primeiro, amplie o slippage ou reduza o valor, confira se o contrato não está pausado e confirme que você está na rede em que o contrato vive. A página da transação no explorer mostra o motivo do revert para falhas mineradas; o guia do Etherscan mostra onde encontrá-lo.
11. Already known, invalid sender e oversized data
"Already known" não é um erro em nenhum sentido prático. O nó já tem exatamente a transação que você enviou, normalmente porque uma biblioteca repetiu um broadcast ou duas carteiras empurraram os mesmos bytes assinados. Espere a original confirmar.
"Invalid sender" significa que o nó não conseguiu recuperar um signatário válido a partir da assinatura. Desde a EIP-155 o chain ID faz parte do que é assinado, então uma transação assinada para a cadeia 1 e enviada para a cadeia 137 recupera lixo e é recusada. Confira o chain ID na configuração de assinatura contra o que o endpoint RPC informa; a lista de chain IDs cobre os números e o caso de incompatibilidade.
"Oversized data" significa que o tamanho em bytes da transação está acima do que o nó aceita no seu pool, o que só acontece com deploys de contrato ou calldata muito grandes. Divida os dados, ou faça o deploy por meio de uma factory.
12. Uma transação que falhou custa gas?
Depende de onde ela falhou. Tudo o que está na primeira família deste guia (nonce, underpriced, insufficient funds, intrinsic gas, teto de taxa, already known, invalid sender, oversized data) é uma rejeição: o nó descartou a transação e nenhum bloco a contém, então nenhuma taxa foi cobrada e não há nada para encontrar no explorer. Reenviar não custa nada a mais.
"Out of gas" e "execution reverted" em uma transação minerada são a segunda família: a transação está em um bloco com status Fail, o validador fez o trabalho e a taxa é paga por inteiro. A documentação do ethereum.org é explícita em dizer que a taxa é paga independentemente de a transação ter sucesso ou falhar. Qualquer ETH ou token que você tentou mover fica onde estava; só a taxa é perdida.
13. Como evitar esses erros em código
Quatro hábitos tiram a maior parte desta lista de um serviço de envio: ler o nonce pendente do nó em vez de manter um contador, pegar as estimativas de taxa do nó para a rede em que você está, estimar o gas antes de assinar e somar uma margem, e conferir o saldo contra o valor mais a taxa no pior caso antes de transmitir. O SDK da ChainGate faz os quatro dentro de transfer(), e expõe o único caso que você precisa tratar por conta própria como um erro tipado:
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;
}O tutorial para enviar cripto em JavaScript mostra o fluxo completo para o Ethereum e as cadeias UTXO, e a documentação do transfer lista os níveis de taxa e o campo missingFunds, que diz exatamente quanta moeda nativa está faltando.
14. Por onde continuar
A maioria desses erros é sobre taxas, então a próxima página a ler é o que são gas fees e como max fee, priority fee e base fee se encaixam, seguida do gas tracker para os preços de cada rede agora. Se uma transação chegou a sair e você precisa descobrir o que aconteceu com ela, o guia sobre hash da transação mostra como consultá-la. E para uma biblioteca TypeScript que cuida de nonces, taxas e verificações de saldo no Ethereum, nas Layer 2 da EVM e no Bitcoin, a ChainGate é o SDK por trás deste site.
Perguntas frequentes
O que significa "nonce too low" na MetaMask?
O número de transação que a MetaMask tentou usar já foi confirmado para aquela conta, normalmente porque outra carteira, outro dispositivo ou uma aceleração usou o número antes, ou porque uma cadeia local foi redefinida. Confira no explorer se a ação já passou, depois limpe os dados de atividade e nonce da MetaMask para aquela rede para que ela ressincronize.
Como corrijo "replacement transaction underpriced"?
Suba tanto a max fee quanto a priority fee da substituta em pelo menos 10 por cento em relação à transação que ela substitui; o aumento mínimo padrão do go-ethereum é 10 por cento. Para cancelar em vez de acelerar, envie 0 ETH para você mesmo com o mesmo nonce e a taxa maior.
O que significa "intrinsic gas too low"?
O gas limit da transação está abaixo do seu custo base fixo, que é 21.000 de gas para uma transferência simples de ETH e mais para transferências de token e chamadas a contrato. Suba o gas limit ou deixe a carteira estimá-lo. A transação foi rejeitada antes da inclusão, então nenhuma taxa foi cobrada.
O que significa "insufficient funds for gas * price + value"?
O saldo da conta na moeda nativa não cobre o valor enviado mais o gas limit multiplicado pela max fee per gas. Ter tokens não basta: o gas é pago em ETH no Ethereum e na Base, em POL na Polygon, em BNB na BNB Smart Chain. Reponha a moeda nativa ou envie menos.
"Execution reverted" custa gas?
Só se a transação foi minerada. Quando a carteira informa o erro durante a estimativa de gas, nada foi enviado e nada foi cobrado. Quando uma transação minerada reverte, a taxa é paga por inteiro e o explorer mostra o status Fail.
Por que minha transação falha com "out of gas" mesmo tendo definido um gas limit?
O limite foi alto o bastante para ser aceito, mas baixo demais para o código do contrato que rodou. A EVM reverte as mudanças e consome todo o gas fornecido, então a taxa é gasta. Reenvie com um limite maior; estimativas do eth_estimateGas mais uma margem evitam isso.
O que significa "max fee per gas less than block base fee"?
A max fee da transação está abaixo da base fee atual, então nenhum bloco pode incluí-la. Suba a max fee, ou espere a base fee cair abaixo do seu teto. Costuma acontecer quando a transação foi assinada antes, com uma taxa fixa no código.
Uma transação rejeitada custa alguma coisa?
Não. Rejeições como nonce too low, transaction underpriced, insufficient funds ou intrinsic gas too low acontecem antes de a transação entrar em um bloco, então nenhuma taxa é cobrada e nada aparece no explorer. Só transações mineradas que ficam sem gas ou revertem custam a taxa.
Esses erros são os mesmos na Base, na Arbitrum, na Polygon e na BNB Smart Chain?
Sim. Essas redes rodam clientes EVM derivados do mesmo código, então as mensagens, as regras de nonce e as verificações de taxa são as mesmas. Os valores mudam: o gas é pago na moeda nativa de cada rede e as taxas mínimas são bem menores do que na mainnet do Ethereum.
Construa com ChainGate
Leve estas ideias para o código — a ChainGate te oferece wallets, transações e RPC gerenciado para Ethereum e mais de 20 blockchains com uma única instalação.