Errors and debugging

TRON API errors fall into three categories with different debugging procedures:

• HTTP-level errors — network or transport failures before the request reaches the node
• Validation errors — the node rejected the transaction before execution; the broadcast response classifies it with a top-level code such as CONTRACT_VALIDATE_ERROR, SIGERROR, or BANDWITH_ERROR, plus a message whose representation depends on visible
• Execution errors — the transaction was accepted into a block but the on-chain execution failed; reported in the transaction info, not the broadcast response

Each category has different debugging steps and different retry implications. Confusing them is a common production bug; for example, creating a replacement while the original broadcast outcome is still unknown can produce duplicate balance changes if both transactions are eventually included successfully.

📘

Prerequisites

• API workflow
• Encoding

Category 1: HTTP-level errors

The request did not complete a round trip — the client never got a JSON response from the node.

Not receiving a business response does not prove that the node never received or processed the request. Reads are generally safe to retry. For transaction broadcasts, re-broadcast the same signed transaction so its txID remains unchanged. For other state-changing requests, check node or on-chain state before deciding whether to retry.

Category 2: Validation errors

The node received the request, parsed it, but rejected it at the validation stage. The transaction never enters the mempool.

When the underlying result is false, /wallet/broadcasttransaction normally omits the result field. Use code and message to identify the failure:

{
  "code": "CONTRACT_VALIDATE_ERROR",
  "message": "636f6e7472616374207061726168657920646f6573206e6f74206d61746368"
}

The code field gives the broad failure category. The message field provides the specific cause. When visible is omitted or false, the node normally returns this field as hex; with visible: true, it may return UTF-8 text.

Common top-level broadcast codes

BANDWITH_ERROR preserves the spelling used by the protocol enum; clients must match this exact value.

Decoding a hex-encoded message

const message = "636f6e7472616374207061726168657920646f6573206e6f74206d61746368";
const decoded = /^(?:[0-9a-fA-F]{2})+$/.test(message)
  ? Buffer.from(message, "hex").toString("utf8")
  : message;
// "contract parahey does not match"

Most SDKs decode automatically. If you process the HTTP response directly, detect the representation before decoding so that a plain-text message is not misinterpreted as hex.

Common validation error subtypes

Retry a validation failure only after correcting its cause. A fresh transaction is not automatically safe when an earlier broadcast outcome is unknown; check whether the original txID was included before authorizing a replacement. Retrying the exact same signed payload succeeds only if the relevant validation conditions changed, such as after topping up the balance.

Category 3: Execution errors

A smart-contract transaction can pass node validation and be included in a block, yet still fail during TVM execution. The transaction receipt records this execution result. Query the following endpoint for the solidified result:

POST /walletsolidity/gettransactioninfobyid
{ "value": "<txid>" }

After receiving the response, first verify that the top-level result is not FAILED, then use receipt.result to determine the TVM execution outcome. The complete receipt.result enum contains 16 values and is defined in protocol/src/main/protos/core/Tron.proto:

For REVERT, decode the revert reason from the transaction's contractResult[0] field — it follows Solidity's standard Error(string) ABI format.

Do not retry an execution error with the same signed payload. The transaction has already been included and executed, and resubmitting the same txID cannot produce a second execution. Diagnose the receipt, correct the cause, and then build and sign a new transaction.

Retry strategy

Different categories have different retry semantics. The summary:

Idempotency

Two safety properties to know:

• Re-broadcasting the same signed transaction is harmless. The exact signed payload retains the same txID, and network deduplication prevents it from executing twice. A node that detects it may return DUP_TRANSACTION_ERROR. Use this property during retries: after a timeout or 5xx response, rebroadcast the same payload rather than creating a replacement.
• A broadcast call that reports no error does not mean that the transaction succeeded. A result: true response means only that the broadcast call returned no error. Keep the original txID and query solidified results: use /walletsolidity/gettransactionbyid for a direct TRX or TRC-10 transfer, and also query /walletsolidity/gettransactioninfobyid for a smart-contract transaction. See Confirmation semantics for endpoint selection and response meanings.

Do not create a replacement immediately for a transaction that was broadcast or whose broadcast outcome is unknown. Follow the safe rebroadcast and replacement procedure and check the original txID against a data source that can provide every solidified block in the transaction's entire possible inclusion interval. Rebuild only after the latest solidified block timestamp reaches the original raw_data.expiration and none of the relevant blocks contains the original transaction. A local clock later than raw_data.expiration, a request timeout, or a single empty {} response from /walletsolidity/gettransactionbyid does not prove that the transaction was never included.

Debugging endpoints

For smart-contract development, simulate calls with triggerconstantcontract before committing real transactions. The endpoint itself does not require a transaction-level fee_limit; convert the returned energy_used with the current getEnergyFee and compare it with the fee_limit planned for the real transaction.

Related resources

• API workflow — what each step in the lifecycle can fail at
• Encoding — encoding mistakes are the most common validation-error source
• Resource model — Bandwidth, Energy, fee_limit
• Smart contract errors — use the exact error message to determine whether OUT_OF_TIME was triggered by an execution timeout or a protocol check
• FAQ — community-curated answers to common errors