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 at validation time, before execution; reported via CONTRACT_VALIDATE_ERROR with a hex-encoded message
• 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, retrying a successfully-broadcast transaction that reverted in execution can produce duplicate balance changes.

📘

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.

These are transport failures; the transaction was never seen by the node. Safe to retry the same request unchanged — there is no risk of duplicate execution.

Category 2: Validation errors (CONTRACT_VALIDATE_ERROR)

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

The broadcast response has this shape:

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

The code field tells you the category of failure (CONTRACT_VALIDATE_ERROR, SIGERROR, BANDWIDTH_ERROR, etc.). The actual cause is in message — hex-encoded.

Decoding the hex message

const hex = "636f6e7472616374207061726168657920646f6573206e6f74206d61746368";
const decoded = Buffer.from(hex, "hex").toString("utf8");
// "contract parahey does not match"

Most SDKs decode automatically; if you see raw hex in your logs, you are reading the API response directly. Always decode before alerting or displaying.

Common validation error subtypes

Safe to retry validation errors only after fixing the underlying cause. Signing a new transaction is always safe; retrying the exact same signed payload only succeeds if the validation environment changed (e.g., balance was topped up).

Category 3: Execution errors

The transaction passed validation, entered the mempool, was included in a block, and then failed at execution time. The broadcast response was successful — the failure shows up only when you query the transaction info. Always query gettransactioninfobyid to verify the final execution state; never treat broadcast success as confirmation that the transaction succeeded on chain.

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

Look at the receipt.result field. The full enum (16 values, 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.

Execution errors are not retryable as-is — the transaction was burned (Energy / TRX consumed, Bandwidth charged) and the same signed payload cannot be reused (TAPOS will be expired or the network will deduplicate). To recover, build a new transaction with corrected parameters and a fresh signature.

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 network deduplicates by txID. A duplicate broadcast returns the same txid and does not double-execute. Use this fact during retries: a 5xx after a successful mempool acceptance is recoverable by re-broadcasting.
• A successful broadcast does not mean a successful execution. Always confirm via gettransactioninfobyid from /walletsolidity/ (the solidified path) before treating the operation as final.

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
• FAQ — community-curated answers to common errors