Broadcast and RPC errors

📘

Prerequisites

• API workflow
• Errors and debugging

This page is the reference for errors returned by the node when you broadcast a transaction, and for rate-limited responses from hosted RPC gateways. Errors that happen after the transaction is included in a block (on-chain execution failures like REVERT / OUT_OF_ENERGY / OUT_OF_TIME) are covered in Smart contract errors; the diagnostic categories and decoded message format are in Errors and debugging.

Broadcast response codes

A wallet/broadcasttransaction call returns a top-level code field on failure. The full set of codes the node may return:

CONTRACT_VALIDATE_ERROR messages

The error code only means "validation failed"; the real reason is in message. Decode it only when the returned value is an even-length hex string. Common plain-text messages are:

For the full hex-decode procedure and the rest of the error-category taxonomy, see Errors and debugging.

SERVER_BUSY — cached-transaction limit exceeded

Broadcast requests return SERVER_BUSY when the current node's cached transaction count exceeds the limit configured by node.maxTransactionPendingSize. The default limit is 2000.

Fix (self-hosted nodes): raise the limit in config.conf according to the node's available memory and CPU capacity:

node.maxTransactionPendingSize = 5000

Restart FullNode after changing the setting. Hosted services such as TronGrid manage this setting themselves. A SERVER_BUSY response from TronGrid means that the backend node handling the request cannot accept additional transactions at that time; it does not establish a network-wide condition. Retry with backoff or switch endpoints.

TronGrid 503 service temporarily unavailable

TronGrid enforces per-IP rate limits across all requests. When your access frequency exceeds the limit, TronGrid returns 4xx / 5xx error codes (most commonly HTTP 503).

Fix:

1. Always send the API key in the TRON-PRO-API-KEY header. Requests without a key are aggressively rate-limited or rejected outright. Header format and request handling are documented in TronGrid rate limits.

2. Reduce request frequency. Limit the burst at DApp start-up; do not poll TronGrid faster than the chain produces blocks — a 3-second slot makes faster-than-3-second polling pointless.

3. Respect Retry-After headers when present. See Errors and debugging — retry strategy.

4. For production volume, consider a customized TronGrid tier (submit a configuration request through the TronGrid console — limits like QPS and total rate are tuned per API key) or running your own full node. See RPC and indexer providers for the comparison.

For the full rate-limit policy, see TronGrid rate limits.

How should I retry when a transaction cannot be found after broadcast?

A broadcast request may return {"result": true, "txid": "..."}, or it may time out without a conclusive response. If subsequent queries do not return the original transaction, its status remains unknown. Preserve the original txID and do not immediately create a new transaction.

result: true means only that the node handling the broadcast request did not report an error. It does not prove that the transaction was included in a block, executed successfully, or solidified. If the request timed out, you also cannot tell whether the node accepted the transaction.

An empty {} response from /walletsolidity/gettransactionbyid means only that this query did not return the original transaction from the solidified chain. Until the latest solidified block timestamp and historical query coverage have been verified, none of the following proves that the original transaction was not included in the solidified chain: the local system time has passed raw_data.expiration, a request timed out, or one query returned an empty response.

When the original transaction cannot be found after broadcast, use the following process to determine whether it entered the solidified chain:

1. Rebroadcast only the original transaction. Preserve the original txID and signed transaction. While the checks below are in progress, if you need to rebroadcast, submit the exact same signed transaction to a reliable, synchronized node. The node still applies normal transaction validation, so rebroadcasting does not guarantee acceptance. Rebroadcasting does not change the txID. A node may return DUP_TRANSACTION_ERROR, but that response does not prove that the transaction is on-chain.

2. Determine the start block.

   • If the application recorded the latest solidified block immediately before the first broadcast, use that block as the start block.
   • If only send logs are available, and they cover every broadcast attempt and the system clock was synchronized, use the last solidified block whose timestamp is earlier than the earliest send time as the start block. The client supplies raw_data.timestamp, so it is not a substitute for the actual send time.
   • If neither source of information is available, subtract 24 hours from raw_data.expiration, find the first solidified block whose timestamp reaches or exceeds that time, and use the following block as the start block. When accepting a transaction or validating a transaction in a block, java-tron rejects it if its expiration is more than 24 hours after the current head-block time. During block validation, the head block is the block preceding the one being validated. Therefore, the first block at or after the calculated time cannot itself have included the original transaction; the following block is the earliest one in which it could have been included.

3. Select a query source and confirm query coverage. Choose a reliable, synchronized node or RPC service that provides both /walletsolidity/getnowblock and /walletsolidity/gettransactionbyid. First, use the source's data-retention configuration or its documented historical-query coverage to confirm that /walletsolidity/gettransactionbyid can retrieve transactions included in the start block and subsequent solidified blocks. If this cannot be confirmed, switch query sources. After selecting a suitable source, call /walletsolidity/getnowblock until block_header.raw_data.timestamp in the returned block reaches or exceeds the original raw_data.expiration, and use that block as the end block. At that point, every block in which the original transaction could have been included has been solidified, and query coverage extends from the start block through the end block.

4. Look up the original transaction and decide what to do next. Query /walletsolidity/gettransactionbyid on the selected source using the original txID:

   • If the transaction is returned, it has entered the solidified chain. Do not create a new transaction under the assumption that the original one was not included. For a smart contract transaction, inclusion in the solidified chain does not mean successful execution. To inspect the complete execution result, resource usage, and other details, use /walletsolidity/gettransactioninfobyid to retrieve the solidified transaction information. If the selected source cannot return that information, use one that can.
   • If the endpoint returns an empty {} response, step 3 has established that every block in which the original transaction could have been included is solidified and that the selected source provides complete query coverage. You can therefore conclude that the original transaction was not included in the solidified chain. Only then should you rebuild, sign, and broadcast a new transaction.

See Errors and debugging — idempotency.

Related resources

• Errors and debugging — error categories, hex decode procedure, retry strategy
• API workflow — construct, sign, broadcast lifecycle
• Confirmation semantics — distinguish the broadcast response, receipt availability, and solidified final state
• Smart contract errors — on-chain execution failures (REVERT, OUT_OF_ENERGY, OUT_OF_TIME)
• Node operations issues — node-side sync and stability problems
• FAQ — Q&A hub