What error codes exist on XRPL?
Last updated:
The XRP Ledger uses an extensive system of error codes to precisely describe transaction outcomes, operational failures, and protocol violations. Understanding these codes is essential for developers building robust applications, as they enable specific error handling, retry logic, and user communication.
Transaction result codes fall into five main categories distinguished by their three-letter prefix. "tes" codes indicate success, though tes SUCCESS is the only success code. "tec" codes mean claimed fee - the transaction was included in a ledger and charged a fee but failed to execute. "tem" codes indicate malformed transactions rejected before ledger inclusion. "ter" codes suggest retry might succeed. "tef" codes represent permanent failures.
Success codes start with tes (Transaction Engine - Success). tesSUCCESS is the standard success code indicating the transaction executed as intended. This is the only tes code in normal use, though the prefix reserves space for potential future success variants.
tec codes (Transaction Engine - Claimed) include dozens of specific failures. tecUNFUNDED_PAYMENT, tecNO_DST_INSUF_XRP, tecPATH_DRY, tecUNFUNDED_OFFER, tecNO_LINE_INSUF_RES, tecDST_TAG_NEEDED, tecNO_PERMISSION, tecNO_AUTH, tecINSUFFICIENT_RESERVE, tecNEED_MASTER_KEY, tecDIR_FULL, tecPATH_PARTIAL, and tecUNFUNDED_ADD all represent operations that failed after being included in a validated ledger.
tem codes (Transaction Engine - Malformed) indicate invalid transactions rejected immediately. temBAD_FEE means the fee is invalid or improperly specified. temBAD_SIGNATURE indicates signature verification failed. temINVALID means the transaction is malformed. temREDUNDANT suggests the operation would have no effect. temBAD_CURRENCY indicates invalid currency codes. temBAD_AMOUNT means amounts are improperly specified. These transactions never reach consensus and charge no fees.
ter codes (Transaction Engine - Retry) suggest temporary failures where resubmission might succeed. terRETRY indicates a generic retry condition. terPRE_SEQ means the sequence number is too high - previous sequence numbers haven't been used yet. terLAST_SEQ occurs when the LastLedgerSequence was exceeded. terQUEUED means the transaction is queued for later processing. These often result from timing or network conditions.
tef codes (Transaction Engine - Failure) represent permanent failures. tefFAILURE is a generic permanent failure. tefPAST_SEQ means the sequence number was already used. tefMAX_LEDGER indicates LastLedgerSequence expired. tefINTERNAL suggests an internal error occurred. tefEXCEPTION means an unexpected exception happened. These transactions won't succeed if resubmitted without changes.
Beyond transaction result codes, API error codes exist for request failures. invalidParams indicates the API request contains invalid parameters. actNotFound means the requested account wasn't found. lgrNotFound indicates the requested ledger doesn't exist. txnNotFound means the requested transaction wasn't found. These codes help applications handle API-level failures distinctly from transaction failures.
RPC error codes include additional categories. noPermission indicates insufficient permissions for the requested operation. tooBusy means the server is too busy to handle the request. noNetwork suggests network connectivity issues. internalError indicates server-side problems. These errors often warrant retry with backoff strategies.
HTTP status codes apply to HTTP/HTTPS API connections. 200 indicates success. 400 means bad request syntax. 404 indicates resource not found. 500 suggests server errors. 503 means service unavailable. Applications using HTTP APIs must handle these alongside XRPL-specific error codes.
WebSocket error codes manage connection issues. Connection refused, connection timeout, unexpected disconnection, and protocol errors all require handling in WebSocket-based applications. Implementing reconnection logic with exponential backoff ensures reliability.
Different XRPL libraries and tools may use additional error codes specific to their implementation. xrpl.js, xrpl-py, and other client libraries sometimes wrap protocol errors in library-specific error types. Understanding both protocol-level and library-level errors ensures comprehensive handling.
Error code documentation is available in the official XRPL documentation, providing exhaustive lists of all defined codes with explanations. However, documentation sometimes lags protocol changes, so monitoring actual error responses and staying current with rippled release notes helps identify new or changed codes.
Robust error handling implements specific logic for expected errors and graceful degradation for unexpected ones. Applications should explicitly handle common errors like tecUNFUNDED_PAYMENT, temBAD_SIGNATURE, and tefMAX_LEDGER while logging and alerting on unexpected errors for investigation.
Error classification guides retry strategies. tem errors shouldn't be retried without fixing the transaction. tec errors might retry after addressing underlying issues. ter errors often benefit from immediate retry. tef errors related to sequence numbers require sequence management fixes. This classification enables intelligent, automated error recovery.
Logging error frequencies helps identify systemic issues. High rates of specific errors might indicate application bugs, user confusion, or integration problems. Monitoring error distributions provides operational visibility and guides improvement efforts.
User-facing error messages should translate technical error codes into clear explanations. Instead of showing "tecUNFUNDED_PAYMENT" to users, display "Insufficient XRP balance. Please ensure your account has enough XRP to cover both the payment and transaction fee." Good error UX requires understanding error semantics to provide helpful guidance.