Navigating failures when sending transactions on the TON blockchain can be challenging, especially as projects and users interact with Telegram Mini Apps, DeFi protocols, and multi-signature swaps. One tool central to diagnosing issues is the exit code—a short value indicating why a TON wallet transaction failed. However, interpreting TON wallet exit codes goes far beyond matching a number to a phrase. Proper troubleshooting requires contextual awareness of wallet version, the live wallet state, and the transaction’s specifics.
Whether you’re a developer or everyday user, understanding what each exit code means—and the risks of incorrect retry attempts—can help keep your TON assets secure. This article guides you through concrete steps for reading exit codes, their common causes, and best practices for resolving issues safely.
Specific Wallet Exit Codes and Their Causes
Each time a TON wallet transaction fails, the contract returns an exit code. These codes represent technical reasons for rejection and are fundamental to secure blockchain operation. Some of the most frequent failure types include:
- Signature verification failure: This means the digital signature attached to the transaction does not match the private key, preventing unauthorized actors from moving funds.
- Replay detection (seqno mismatch): TON wallets use a sequence number (seqno) to prevent duplicates. If the seqno is out of order or already used, the replay protection triggers an exit code.
- Subwallet mismatches: With multi-wallet accounts, transactions may reference the wrong subwallet, generating a specific failure code.
- Transaction expiry (valid-until exceeded): Transactions can specify an expiration time. Submitting after this time results in an exit code for expiry.
Each exit code’s meaning can change depending on the wallet contract version you are using. It’s critical to refer to official documentation and understand which version your wallet implements. The most authoritative reference for historical and current exit codes is the TON wallet history documentation.
TON Drop Hub take: Don’t just rely on the exit code itself. Before taking further action, verify the recipient address, the TON (or Jetton) amount, and the wallet’s current state on-chain. An exit code alone does not guarantee that a retry will fix the problem—and in some cases, an automatic retry can cause additional issues or loss of assets.
Context: Wallet Version and Replay Logic
A repeat mistake made by less-experienced users is assuming that all exit codes related to validity windows or replay logic indicate a “safe to retry” situation. In reality, each error code marks a distinct technical event. It could be a signature problem, a mismatch with the expected subwallet, or an expired transaction. No exit code, on its own, verifies that a reattempt will succeed.
TON’s replay protection system highlights this risk. The seqno mechanism ensures transactions run in strict order. If you try to “replay” an old transaction, or resend a transaction after an error without checking the current seqno, you’ll encounter consistent rejections. Worse, there is a risk you could inadvertently send assets to the wrong recipient or with incorrect parameters if the wallet’s state has changed since the last attempt.
When dealing with transactions in Telegram Mini Apps or DeFi tools, exit codes should serve as a diagnostic context—not as a green light to repeat operations. Always relate an exit code back to the wallet version. For contract developers and advanced users, TON guides provide detailed instructions for version-specific troubleshooting.
TON Drop Hub take: Treat exit codes as signals, not as instructions to retry. A misunderstood code can lead to repeated lost transactions or security risks for your wallet and related apps.
Best Practices for Retrying Failed Transactions
Before retrying any failed TON wallet transaction, follow a multi-step check:
1. Double-check the recipient address: An incorrect address could send assets beyond your recovery.
2. Verify the transfer amount: Errors in amount entry cannot be reversed later.
3. Inspect the live wallet state on-chain: The wallet may have received other transactions, or its seqno may have changed since your previous attempt.
4. Check for transaction expiry: If the valid-until time has passed, generate a fresh transaction, not a repeat.
5. Review wallet version: Confirm you are using the correct reference point for exit code interpretation. Official exit code details change with contract revisions (reference documentation).
There is no universal, automated way to “fix” a failed transaction. Repeating an action without investigation can compound errors or lead to permanent loss. TON assets, once lost or misdirected, are very difficult to recover.
TON Drop Hub take: Always treat exit codes as the start, not the end, of your troubleshooting process. Re-verify every transaction element before retrying. When in doubt, start from scratch with a new, carefully constructed transaction.
If you need additional support for your specific wallet version, wallet type, or app integration, consult the comprehensive TON guides.