Can XRPL transactions fail?
Last updated:
Yes, XRPL transactions can fail, and understanding failure modes is crucial for developers building on the network. Transaction failures occur for numerous reasons, each with specific error codes helping developers diagnose and handle problems appropriately.
Transaction failures fall into several categories based on when they occur in the transaction lifecycle. Rejections happen before transactions enter the ledger, while failed transactions are included in validated ledgers with failure codes. This distinction is important - rejected transactions never consume sequence numbers or transaction fees, while failed transactions do consume both.
Common rejection reasons include malformed transactions, invalid signatures, insufficient XRP for the base reserve, incorrect sequence numbers, or transactions referencing non-existent accounts. Rippled servers reject these immediately, before submitting them to the consensus process. No fee is charged because the transaction never reaches validators.
Failed transactions pass initial validation and enter the consensus process but cannot execute successfully. These failures include insufficient XRP for the transaction fee, destination accounts not accepting the payment, trust line limits being exceeded, or conditional payments where conditions aren't met. The transaction fee is consumed, and the account's sequence number increments.
The distinction between tesSUCCESS (successful), tec codes (claimed fee, failed execution), tem codes (malformed, rejected), ter codes (retry possible), and tef codes (permanent failure) provides precise failure categorization. Understanding these codes helps developers implement appropriate retry logic and error handling.
Insufficient funds represent a common failure scenario. If an account attempts to send more XRP than it holds, minus reserves, the transaction fails with a tecUNFUNDED_PAYMENT result. The transaction fee is still charged, potentially leaving the account with even less XRP. Applications should verify sufficient funds before submitting transactions.
Destination tag requirements can cause failures when users send payments without required tags. Exchanges and services often require destination tags to identify intended recipients. Transactions missing required tags fail with tecNO_DST_INSUF_XRP or are rejected, protecting users from lost funds.
Partial payment flags prevent some failures in cross-currency transactions. Without the partial payment flag, if the full destination amount cannot be delivered due to liquidity constraints, the transaction fails. With the flag enabled, the transaction succeeds delivering whatever amount is possible, up to the specified maximum.
Escrow and payment channel transactions include numerous potential failure scenarios. Escrows can fail if conditions aren't met, finish times haven't passed, or cryptographic conditions are incorrect. Payment channels fail if signature verification fails, amounts exceed channel capacity, or channels have already expired.
Pathfinding limitations cause failures in complex currency conversions. If the specified maximum path length is exceeded, no path exists between source and destination currencies, or liquidity is insufficient, cross-currency payments fail. The pathfinding API helps developers identify viable payment paths before submission.
Transaction expiration through LastLedgerSequence prevents indefinite pending states. If a transaction isn't included in a validated ledger by the specified ledger index, it becomes permanently invalid. This mechanism allows applications to detect failed submissions and retry without risking duplicate payments.
Robust applications implement comprehensive error handling checking transaction results before considering operations complete. Monitoring provisional transaction results before final validation, implementing exponential backoff for retries, and maintaining transaction logs ensures reliable operation despite occasional failures.
The XRPL's deterministic execution means identical transactions produce identical results. This predictability allows developers to test failure scenarios accurately and implement reliable error recovery. Understanding the specific conditions causing different failure codes enables building resilient applications that handle edge cases gracefully.