Erreurs de transaction Ethereum expliquées : ce que signifie chaque message et comment le corriger

1. D'où viennent ces messages d'erreur ?

Presque tous les wallets, bibliothèques et fournisseurs RPC transmettent tel quel le texte d'erreur produit par go-ethereum, le client Ethereum le plus répandu, et les clients des réseaux Layer 2 réutilisent les mêmes chaînes. MetaMask les enveloppe dans sa propre boîte de dialogue, ethers.js ajoute un code comme NONCE_EXPIRED ou REPLACEMENT_UNDERPRICED, et un fournisseur RPC les renvoie sous forme d'erreur JSON-RPC avec le code -32000. En dessous, le message est le même.

Le nœud exécute deux séries de vérifications distinctes. La première a lieu quand il reçoit la transaction : le nonce est-il correct, les frais sont-ils acceptables, le gas limit est-il raisonnable, l'expéditeur peut-il payer. Une transaction qui échoue ici est écartée et rien n'est enregistré on-chain. La seconde a lieu quand la transaction est exécutée dans un bloc : le code du contrat se termine-t-il dans la limite de gas sans revert. Une transaction qui échoue ici est quand même minée, avec le statut Fail sur l'explorer, et les frais sont dépensés.

Savoir à quelle famille appartient une erreur vous apprend deux choses à la fois : si vous avez perdu de l'argent, et si la correction est de votre côté (la transaction) ou du côté du contrat (les entrées).

2. Référence rapide : toutes les erreurs courantes

Les chaînes exactes, dans l'ordre où vous avez le plus de chances de les rencontrer. La formulation vient du code source de go-ethereum ; les wallets la raccourcissent parfois.

3. Que signifie "nonce too low" ?

Chaque compte numérote ses transactions à partir de zéro, et chaque numéro ne peut servir qu'une fois. "Nonce too low" signifie que la transaction que vous venez d'envoyer porte un numéro que le réseau a déjà confirmé pour ce compte. Le nœud compare le nonce de votre transaction au prochain nonce attendu du compte et refuse tout ce qui est en dessous.

Cela arrive quand l'idée que le wallet se fait du prochain nonce est périmée : une transaction a été envoyée depuis le même compte dans un autre wallet ou sur un autre appareil, une accélération ou une annulation a déjà pris le numéro, ou une chaîne de développement locale a été redémarrée, si bien que le compteur du compte est revenu à zéro alors que MetaMask a continué de compter. Sur un hardware wallet, l'erreur apparaît aussi quand une transaction est signée deux fois.

La correction consiste à laisser le wallet se resynchroniser. Cherchez d'abord l'adresse sur l'explorer : si ce que vous vouliez faire est déjà passé sous ce nonce, ne renvoyez pas. Si le wallet continue de proposer un numéro périmé, l'option "Delete activity and nonce data" (Supprimer les données d'activité et de nonce) de MetaMask (Paramètres, Outils de développement) efface le compteur local pour le réseau courant. MetaMask précise qu'elle est irréversible, qu'elle ne touche que le réseau courant et qu'elle ne modifie pas votre solde. Dans du code, lisez le prochain nonce avec eth_getTransactionCount et le tag "pending" avant de signer, plutôt que de tenir votre propre compteur.

4. Que signifie "nonce too high" ?

L'écart inverse. Le nonce de la transaction est au-dessus de la prochaine valeur attendue du compte, donc il y a un trou : un numéro inférieur n'a pas encore été confirmé. Les nœuds gardent une telle transaction dans une file plutôt que de l'exécuter, et certains la rejettent d'emblée avec ce message.

Cause typique : un lot de transactions dont l'une des premières a été écartée, ou une réinitialisation de chaîne locale dans l'autre sens (la chaîne a été réinitialisée mais pas le wallet, donc le wallet envoie le nonce 40 à une chaîne qui attend le nonce 0). Comblez le trou en envoyant le nonce manquant, ou effacez les données d'activité du wallet comme indiqué plus haut.

5. Que signifie "replacement transaction underpriced" ?

Vous avez tenté de remplacer une transaction en attente (accélérer, annuler, ou simplement renvoyer avec le même nonce) et la nouvelle ne paie pas assez de plus que l'ancienne. Le nœud n'échange une transaction en attente contre une autre de même nonce que si les frais augmentent d'un pourcentage minimum ; dans go-ethereum, cette hausse de prix vaut 10 % par défaut, et elle s'applique à la fois à la max fee et à la priority fee.

Le nonce est correct ; c'est le prix qui pose problème. Augmentez les deux champs de frais d'au moins 10 % par rapport à la transaction en attente, pas par rapport au tarif actuel du réseau. Pour la boîte de dialogue voisine "transaction underpriced", MetaMask recommande lui-même une priority fee d'au moins 10 % plus élevée et une max fee d'au moins 30 % plus élevée. Pour annuler plutôt qu'accélérer, envoyez 0 ETH à votre propre adresse avec le même nonce et les frais relevés, comme décrit dans le guide des erreurs de MetaMask. Dans les deux cas, le remplacement reçoit un nouveau hash de transaction et l'ancienne est écartée.

6. Que signifie "transaction underpriced" ?

Sans le mot "replacement", il s'agit d'une simple vérification de prix : les frais de votre transaction sont inférieurs à ce que le nœud accepte de garder dans son pool. Les nœuds fixent un gas price minimum pour tenir le spam à l'écart, et pendant une période chargée l'estimation "basse" d'un wallet peut tomber en dessous. Le message voisin "transaction gas price below minimum" veut dire la même chose.

Relevez la max fee et la priority fee, puis renvoyez. Rien n'a été enregistré on-chain, donc il n'y a aucune transaction bloquée à effacer. Si vous la voyez régulièrement sur un réseau donné, c'est que le minimum de ce réseau est plus élevé que la valeur par défaut de votre wallet ; les pages par réseau du gas tracker affichent le tarif en vigueur.

7. Que signifie "insufficient funds for gas * price + value" ?

Le solde de l'expéditeur en coin natif doit couvrir le montant envoyé plus les frais dans le pire des cas, c'est-à-dire le gas limit multiplié par la max fee per gas. Cette règle est inscrite dans l'EIP-1559 : le signataire doit pouvoir payer gas_limit fois max_fee_per_gas, en plus de la valeur. Le nœud vérifie par rapport au maximum, pas par rapport à ce que la transaction coûtera réellement, donc une transaction peut échouer à cette vérification même si les frais finaux auraient tenu dans le solde.

Trois causes couvrent presque tous les cas. Vous détenez des tokens mais pas de coin natif : de l'USDC sur Base a besoin d'ETH pour le gas, de l'USDT sur Polygon a besoin de POL, n'importe quoi sur BNB Smart Chain a besoin de BNB. Vous envoyez tout votre solde sans rien laisser pour les frais : soustrayez d'abord les frais maximum. Ou bien le gas limit est gonflé par un appel de contrat, donc le pire des cas est bien au-dessus du coût réel.

Correction : rechargez le coin natif, envoyez un montant plus petit, ou baissez la max fee ou le gas limit s'ils sont surestimés. Le message voisin "insufficient funds for transfer" signifie que la valeur à elle seule dépasse le solde, avant même de compter le gas.

8. Intrinsic gas too low, out of gas et erreurs de gas limit

Quatre messages concernent le gas limit, et ils échouent à des moments différents. "Intrinsic gas too low" est un rejet avant inclusion : chaque transaction a un coût de base fixe avant qu'aucun code ne s'exécute, 21,000 gas pour un simple transfert plus un supplément par octet de données, et votre gas limit est en dessous. La documentation d'ethereum.org sur le gas fixe le transfert standard à 21,000 unités ; un transfert de token ou un appel de contrat en demande davantage. Relevez la limite, ou laissez le wallet ou la bibliothèque l'estimer.

"Out of gas" est la version après inclusion. La limite couvrait le coût de base, la transaction a été minée, puis le code du contrat a eu besoin de plus que ce que la limite autorisait. L'EVM annule chaque changement d'état mais, comme le dit la même documentation, tout le gas fourni est quand même consommé pour le travail effectué. Les frais sont perdus et la transaction apparaît comme échouée sur l'explorer. Renvoyez avec une limite plus élevée ; c'est pour cette raison que les wallets ajoutent généralement une marge au-dessus de l'estimation.

"Exceeds block gas limit" signifie que la limite que vous avez fixée dépasse ce qu'un bloc entier peut contenir sur ce réseau. "Transaction gas limit too high" est plus récent : depuis l'EIP-7825, une seule transaction ne peut pas demander plus de 16,777,216 gas (2 puissance 24), et une transaction au-dessus de ce plafond est rejetée. Les deux se corrigent en baissant la limite ; une transaction légitime n'a jamais besoin de s'approcher de ces chiffres.

9. Erreurs de max fee et de priority fee

Depuis l'EIP-1559, une transaction porte deux champs de frais : la max fee per gas, qui est le maximum que vous paierez par unité, et la max priority fee per gas, le tip pour le validateur. Le protocole impose deux relations entre eux et la base fee du bloc, et chacune a sa propre erreur.

"Max fee per gas less than block base fee" : votre max fee est inférieure à la base fee actuelle, donc la transaction ne peut être incluse quel que soit le tip. Cela touche les transactions signées pendant une période calme et diffusées après la hausse de la base fee, ainsi que les transactions construites avec des frais codés en dur. Relevez la max fee, ou attendez : la base fee bouge bloc par bloc et la transaction redevient valide si elle repasse sous votre plafond.

"Max priority fee per gas higher than max fee per gas" : le tip dépasse le plafond total, ce que la spécification interdit parce que la base fee est servie en premier et que le tip ne peut venir que de ce qui reste. Fixez la priority fee au niveau de la max fee ou en dessous. Une transaction correctement construite a une max fee égale à environ deux fois la base fee plus le tip, ce qui laisse à la base fee la place de monter pendant l'attente.

10. Que signifie "execution reverted" ?

Le contrat que vous avez appelé a interrompu l'exécution volontairement. Les instructions require, revert et assert de Solidity aboutissent toutes à ce message, souvent suivi de la chaîne de raison propre au contrat : "ERC20: transfer amount exceeds allowance", "UniswapV2Router: INSUFFICIENT_OUTPUT_AMOUNT", "Pausable: paused" et ainsi de suite. Quand la raison est vide, vous ne voyez que "execution reverted" ou les données d'erreur brutes.

La plupart du temps, vous le voyez avant l'envoi, parce que le wallet fait passer l'appel par eth_estimateGas et que la simulation fait un revert ; MetaMask signale alors qu'il ne peut pas estimer le gas. C'est la version bon marché : rien n'a été envoyé. La version coûteuse est une transaction qui a passé la simulation, a été minée, et a fait un revert on-chain parce que l'état a changé entre-temps (le prix d'un swap a dépassé votre slippage, quelqu'un d'autre a acheté le dernier article, une deadline est passée). Elle apparaît en Fail sur l'explorer et les frais sont payés.

La correction n'est jamais un gas limit plus élevé. Lisez la chaîne de raison, puis changez les entrées : approuvez d'abord le token, élargissez le slippage ou réduisez le montant, vérifiez que le contrat n'est pas en pause, et confirmez que vous êtes sur le réseau où vit le contrat. La page de transaction de l'explorer affiche la raison du revert pour les échecs minés ; le guide Etherscan montre où la trouver.

11. Already known, invalid sender et oversized data

"Already known" n'est pas une erreur au sens pratique. Le nœud détient déjà exactement la transaction que vous avez envoyée, généralement parce qu'une bibliothèque a réessayé une diffusion ou que deux wallets ont poussé les mêmes octets signés. Attendez que l'originale se confirme.

"Invalid sender" signifie que le nœud n'a pas pu récupérer un signataire valide à partir de la signature. Depuis l'EIP-155, le chain ID fait partie de ce qui est signé, donc une transaction signée pour la chaîne 1 et envoyée à la chaîne 137 produit un signataire aberrant et est refusée. Comparez le chain ID de la configuration de signature à ce que renvoie l'endpoint RPC ; la liste des chain ID couvre les nombres et le cas de non-concordance.

"Oversized data" signifie que la taille en octets de la transaction dépasse ce que le nœud accepte dans son pool, ce qui n'arrive qu'avec de très gros déploiements de contrats ou de très gros calldata. Découpez les données, ou déployez via une factory.

12. Une transaction échouée coûte-t-elle du gas ?

Cela dépend de l'endroit où elle a échoué. Tout ce qui relève de la première famille de ce guide (nonce, underpriced, insufficient funds, intrinsic gas, plafond de frais, already known, invalid sender, oversized data) est un rejet : le nœud a écarté la transaction et aucun bloc ne la contient, donc aucuns frais n'ont été facturés et il n'y a rien à trouver sur l'explorer. Renvoyer ne coûte rien de plus.

"Out of gas" et un "execution reverted" miné forment la seconde famille : la transaction est dans un bloc avec le statut Fail, le validateur a fait le travail, et les frais sont payés intégralement. La documentation d'ethereum.org est explicite : les frais sont payés que la transaction réussisse ou échoue. Les ETH ou les tokens que vous tentiez de déplacer restent où ils étaient ; seuls les frais sont perdus.

13. Comment éviter ces erreurs dans du code

Quatre habitudes font disparaître l'essentiel de cette liste d'un service d'envoi : lire le nonce pending depuis le nœud au lieu de tenir un compteur, prendre les estimations de frais du nœud pour le réseau sur lequel vous êtes, estimer le gas avant de signer et ajouter une marge, et vérifier le solde par rapport au montant plus les frais dans le pire des cas avant de diffuser. Le SDK ChainGate fait les quatre à l'intérieur de transfer(), et expose le seul cas que vous devez gérer vous-même sous forme d'erreur typée :

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;
}

Le tutoriel pour envoyer des cryptos en JavaScript montre le flux complet pour Ethereum et les chaînes UTXO, et la documentation de transfer liste les niveaux de frais et le champ missingFunds qui vous dit exactement combien de coin natif il manque.

14. Pour aller plus loin

La plupart de ces erreurs concernent les frais, donc la page suivante à lire est ce que sont les gas fees et comment max fee, priority fee et base fee s'articulent, puis le gas tracker pour les tarifs de chaque réseau en ce moment. Si une transaction est bien partie et que vous devez savoir ce qu'elle est devenue, le guide du hash de transaction montre comment la retrouver. Et pour une bibliothèque TypeScript qui gère les nonces, les frais et les vérifications de solde sur Ethereum, les Layer 2 EVM et Bitcoin, ChainGate est le SDK derrière ce site.

Questions fréquentes