Errore max-fee-exceeded Bitcoin Core: cause e soluzione

L’errore max-fee-exceeded in Bitcoin Core indica che una transazione supera il limite di fee rate applicato al controllo. Non significa automaticamente che la commissione sia troppo bassa o che basti attendere un blocco. Prima di cambiare un parametro, bisogna verificare unità di misura, importi degli input, output e resto.

La risposta breve è questa: maxfeerate è un tetto di sicurezza, non la commissione da assegnare alla transazione. Aumentarlo non corregge un pagamento costruito male; può soltanto consentire di procedere con una commissione che prima veniva rifiutata. Questa guida riguarda un problema RPC preciso e non sostituisce il controllo del wallet.

Che cosa significa max-fee-exceeded

La documentazione di testmempoolaccept descrive un controllo di ammissione alla mempool. Il risultato può contenere un motivo di rifiuto. Il parametro massimo del fee rate va distinto sia dalle regole di consenso sia dalla scelta economica della commissione che vuoi pagare.

Le spiegazioni qui sono riferite alle pagine RPC di Bitcoin Core 30.0.0, non a una presunta versione universale di tutti i servizi. Se usi un provider, una libreria o una versione diversa, leggi l’help effettivo e la risposta completa. Un messaggio riassunto dall’interfaccia può omettere il punto in cui il controllo è avvenuto.

Conserva il nome del metodo chiamato, i parametri non sensibili e il messaggio restituito. Evita di pubblicare credenziali RPC, seed, chiavi o transazioni firmate non ancora inviate. Per una segnalazione tecnica bastano spesso metodo, versione e valori ricostruiti con dati di prova, senza esporre informazioni reali del wallet.

maxfeerate non è la fee pagata

La pagina sendrawtransaction distingue il limite dal contenuto della transazione. Una transazione già costruita e firmata incorpora input e output: la differenza economica non viene riscritta passando un altro tetto al comando di invio.

È la differenza fra un allarme e il problema che segnala. Se il valore previsto è sbagliato, alzare l’allarme lascia intatto l’errore. Per modificare la fee può essere necessario tornare al processo di costruzione della transazione e poi firmare la versione corretta, con tutte le verifiche pertinenti.

Non usare come soluzione standard il valore che disabilita il controllo. La possibilità tecnica di superare una protezione non dimostra che l’importo sia intenzionale. Se non riesci a ricostruire la commissione, fermati invece di cercare un parametro abbastanza grande da far sparire il messaggio.

Convertire BTC/kvB in sat/vB senza confondersi

Il parametro delle RPC citate è espresso in BTC per kilovirtual byte. Molti wallet mostrano invece satoshi per virtual byte. Per passare da sat/vB a BTC/kvB dividi per 100.000; per la conversione inversa moltiplichi per 100.000. Il numero sembra diverso perché cambia l’unità, non perché cambia necessariamente il costo.

Questa tabella è una conversione aritmetica, non un consiglio sulle fee attuali. Non stabilisce quale valore garantisca una conferma. Per il funzionamento generale delle commissioni puoi leggere la guida alle fee Bitcoin; qui il problema è evitare di confrontare numeri che appartengono a unità diverse.

Per esempio, impostare mentalmente “10” perché il wallet parla di 10 sat/vB e copiarlo in un campo BTC/kvB è un errore di unità. Prima di inviare qualsiasi richiesta, scrivi accanto a ogni valore la sua unità. Non affidarti al nome abbreviato di una variabile nell’applicazione.

Un esempio completo con fee e resto

Consideriamo importi inventati: input complessivi di 100.000 satoshi, un pagamento da 70.000 satoshi e un output di resto da 28.000. La fee è 2.000 satoshi, perché 100.000 meno 70.000 meno 28.000 dà 2.000. Con una dimensione finale di 200 vB, il fee rate è 10 sat/vB.

Se il resto viene omesso e rimane soltanto l’output da 70.000, la differenza diventa 30.000 satoshi. Nell’esempio, mantenendo per semplicità una dimensione ipotetica di 200 vB, il rapporto sarebbe 150 sat/vB. In una transazione reale anche la dimensione cambia quando togli un output: va ricalcolata, non riutilizzata alla cieca.

Il punto dell’esempio non è affermare che 150 sat/vB superi il limite predefinito di Core. Mostra come un errore di resto possa alterare il costo, con o senza un rifiuto automatico. Il tetto applicato al tuo caso deve essere identificato separatamente. Gli UTXO Bitcoin aiutano a capire perché si spendono input interi e si ricrea un resto.

Quali controlli fare prima del broadcast

1. Verifica rete, nodo o provider e versione realmente utilizzati.
2. Identifica il metodo che restituisce il rifiuto e il limite applicato.
3. Ricostruisci gli importi degli output precedenti spesi dagli input.
4. Controlla destinatari, importi e output di resto della nuova transazione.
5. Calcola fee totale e fee rate usando la dimensione appropriata.
6. Confronta il risultato con il budget intenzionale e con il tetto, nella stessa unità.

La decodifica della transazione mostra struttura e dimensioni, ma non recupera magicamente tutti gli importi degli output precedenti. Non confondere un riferimento a un input con la conoscenza del suo valore. Se questi dati mancano, non hai ancora un calcolo affidabile della fee.

Se lavori con una PSBT, analyzepsbt può fornire informazioni e stime quando sono disponibili i dati necessari. Una dimensione stimata non va presentata come misura finale già verificata. Il controllo va ripetuto sul risultato effettivamente destinato all’invio.

Comandi di consultazione, senza inviare transazioni

Nel tuo ambiente puoi iniziare dall’help locale. I comandi seguenti consultano informazioni: non costruiscono, firmano o trasmettono un pagamento. Presuppongono un’installazione configurata e raggiungibile; non servono password o chiavi private da incollare nell’articolo.

bitcoin-cli help testmempoolaccept
bitcoin-cli help decoderawtransaction
bitcoin-cli help analyzepsbt

Le prove con dati reali richiedono comunque attenzione alla privacy. Una transazione firmata contiene un’autorizzazione spendibile se valida: non caricarla su siti casuali per farti calcolare una commissione. Per esercitarti, usa un ambiente di test separato e dati senza valore economico, non una copia delle credenziali di produzione.

Perché un test positivo non garantisce la conferma

Un controllo locale risponde rispetto allo stato e alle regole del nodo in quel momento. Non certifica che tutti i nodi accetteranno la transazione, che venga trasmessa o che un miner la includa entro un tempo determinato. Testare, inviare e confermare sono passaggi distinti.

Nel risultato di testmempoolaccept, alcuni campi possono essere assenti quando la transazione non è stata accettata o completamente valutata. Non programmare un’applicazione come se ogni risposta contenesse sempre gli stessi valori. Prima interpreta l’esito, poi leggi i campi disponibili; un dato mancante non equivale a zero.

Se la transazione è già in circolazione e ha una fee insufficiente, il problema è diverso dal tetto massimo. I meccanismi RBF e CPFP hanno requisiti propri e non sono una cura universale per ogni errore RPC. Prima di cambiare procedura, accerta quale versione sia stata effettivamente trasmessa.

Errori simili da non scambiare

Se usi un servizio esterno, chiedi anche dove nasce la risposta: dal nodo Bitcoin Core, da un gateway o dal codice dell’applicazione. Un servizio può applicare una propria politica e trasformare il messaggio prima di mostrarlo. Annotare il livello responsabile evita di cambiare una configurazione locale che non partecipa affatto a quella richiesta. Non attribuire automaticamente ogni valore letto online al provider che stai usando.

Prima di correggere un’integrazione, prepara un caso con quantità note e controlla separatamente conversione e riconciliazione degli importi. Usa una rappresentazione numerica che non introduca arrotondamenti involontari. Il test dovrebbe respingere un’unità sbagliata, non soltanto accettare l’esempio corretto. È un criterio di qualità del software, non un invito a trasmettere pagamenti reali per tentativi.

Un limite minimo riguarda un importo troppo basso rispetto al controllo applicato; max-fee-exceeded riguarda il superamento di un massimo. “Input mancanti” richiede invece di capire la disponibilità degli output spesi. Un errore di decodifica riguarda il formato. Alzare maxfeerate non risolve automaticamente nessuno di questi altri casi.

Anche maxburnamount è un parametro distinto: riguarda determinati output riconosciuti come non spendibili e non è il budget delle commissioni. Non aumentarlo per tentare di correggere una fee. Una protezione basata su determinate forme di output non dimostra inoltre che ogni altro indirizzo o script sia recuperabile dal destinatario previsto.

Domande frequenti

Posso risolvere aspettando?

Non se il motivo è soltanto che gli stessi byte superano lo stesso tetto. Il tempo non ricrea il resto né cambia una conversione sbagliata. Può cambiare il contesto di rete, ma prima occorre capire il controllo che ha prodotto il messaggio.

Devo aumentare la commissione?

Non come risposta a questo specifico messaggio. Prima ricostruisci il costo già incorporato nella transazione. Confondere un massimo superato con una fee minima insufficiente può portare a correggere il problema nella direzione sbagliata.

Qual è il parametro giusto per tutti?

Non esiste un valore universale da copiare. Il tetto è una scelta di protezione da confrontare con importi e unità verificati, non una raccomandazione di mercato. La documentazione della tua versione e le condizioni del provider restano il riferimento operativo.

Il rifiuto dimostra che non è stato inviato nulla?

Non ricostruisce da solo la storia completa. Se altre chiamate o altri servizi hanno già trasmesso la stessa transazione, un rifiuto successivo non li annulla. Verifica l’identità della transazione e lo stato del processo prima di assumere che nessun invio sia avvenuto.

La soluzione a max-fee-exceeded parte quindi dai dati, non dal bypass: transazione corretta, importi riconciliati, unità esplicite e limite consapevole. Se uno di questi elementi rimane incerto, il passo sicuro è interrompere l’invio e chiarirlo. Far scomparire un errore non basta a rendere corretto un pagamento.