Errors

Error format

Errors come back in one of three shapes. Most endpoints use the first one; the other two exist on specific paths and are listed here so your client does not miss an error code it is looking for. Standard. A code for programmatic handling, nested under detail.error:

{
  "detail": {
    "error": {
      "code": "INSUFFICIENT_BALANCE",
      "message": "Insufficient balance. Required: 12.5 TRX, available: 3.1 TRX"
    }
  }
}

Account-level rate limit. The same fields, but at the top level, without detail — this response is produced before the request reaches the endpoint:

{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}

Flat. The withdrawal verification steps put code next to detail, and detail holds the message itself:

{"detail":"Passkey verification required","code":"PASSKEY_REQUIRED"}

Not every response carries a code. Request validation failures come back in the framework’s own format, where detail is an array of field errors rather than a string, and a few internal checks return {"detail": "..."} with a plain message. Some 422 responses do carry a code in the standard shape — a reused idempotency key, for example.

Read the code from the first of these that is present: detail.error.code, then error.code, then code. Fall back to the HTTP status when none of them is there, and never assume detail is a string: it is an object in the standard shape and an array in a validation error.

HTTP status codes

Code	Meaning
`200`	Success
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid API key
`402`	Payment required — account balance too low
`403`	Forbidden — key lacks the required scope, IP not whitelisted, or verification required
`404`	Not found
`409`	Conflict — duplicate request or resource conflict
`422`	Validation error — check request body
`429`	Rate limit exceeded — see Rate Limits
`500`	Server error
`503`	Temporarily unavailable — retry shortly

Common error codes

Returned in the standard shape, under detail.error.code:

Code	Status	Description
`INVALID_TOKEN`	`401`	API key missing, unknown, or disabled
`ACCOUNT_BLOCKED`	`403`	API access blocked for this account
`FORBIDDEN`	`403`	The key lacks the scope this endpoint requires, or the request IP is not on the key’s whitelist
`NODE_API_KEY_ONLY`	`403`	A Node API key was sent to this API — it works only at `node.tronrental.com`
`INSUFFICIENT_BALANCE`	`402`	Account balance too low for this operation
`IDEMPOTENCY_KEY_REUSED`	`422`	This Idempotency-Key was already used with a different request body
`IDEMPOTENCY_KEY_TOO_LONG`	`422`	Idempotency-Key is longer than 64 characters
`INVALID_ADDRESS`	`400`	Not a valid TRON address
`CONTRACT_ADDRESS_NOT_SUPPORTED`	`400`	Target is a smart contract — TRON forbids delegating resources to it
`INVALID_VOLUME`	`400`	Requested amount is outside the allowed range
`INVALID_DURATION`	`400`	Duration is not one of the accepted values
`ORDER_NOT_FOUND`	`404`	Order ID does not exist
`RATE_LIMIT_EXCEEDED`	`429`	Too many requests — see Rate Limits

Node API (node.tronrental.com) has error codes of its own, in a different format — see Node API → Limits and errors.

INSUFFICIENT_BALANCE is not used everywhere. POST /api/v1/smart-mode/activate and POST /api/v1/transfer-packages/buy report the same condition as 400 with a message and no code: {"detail":{"error":{"message":"Insufficient balance"}}}. On those two endpoints, do not detect a funding problem by the code alone.

Auto Refill codes

Returned in the standard shape by the Auto Refill endpoints:

Code	Status	Description
`AUTOREFILL_ADDRESS_TAKEN`	`409`	The account already has a rule for this address and resource — edit that rule instead
`AUTOREFILL_LIMIT_REACHED`	`409`	The account already has 20 rules for this resource; the limit is also in `error.limit`
`AUTOREFILL_IN_PROGRESS`	`409`	A refill for the rule is being bought right now — retry the edit or delete in a minute
`AUTOREFILL_DISABLED`	`503`	Auto Refill for this resource is temporarily switched off; returned only when creating a rule. No rule was created — try again later
`NOT_FOUND`	`404`	No such rule on the account

Withdrawal verification codes

POST /api/v1/account/withdrawal returns these verification codes in the flat shape, with code next to detail. Other errors on the same endpoint use the standard shape:

Code	Status	Description
`WITHDRAW_SCOPE_REQUIRED`	`403`	The API key lacks the `withdraw` scope
`2FA_REQUIRED`	`403`	2FA must be enabled, or a code must be supplied
`IP_WHITELIST_REQUIRED`	`403`	The key needs an IP whitelist before it can withdraw
`PASSKEY_REQUIRED`	`403`	The account has a passkey — withdrawal requires it
`INVALID_PASSKEY`	`403`	Passkey challenge is invalid, expired, or not yours
`INVALID_2FA_CODE`	`403`	2FA or backup code rejected
`RATE_UNAVAILABLE`	`503`	Exchange rate temporarily unavailable — retry shortly

Retry strategy

Retry 5xx responses with exponential backoff. For 429, prefer the Retry-After header when the response carries one, and check the body first — not every 429 is a rate limit (see Rate Limits).

import time
import requests

def api_call_with_retry(url, **kwargs):
    for attempt in range(3):
        resp = requests.get(url, **kwargs)
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
            continue
        if resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        return resp
    raise Exception("Max retries exceeded")

Getting Started

TRON Energy

Error format

HTTP status codes

Common error codes

Auto Refill codes

Withdrawal verification codes

Retry strategy

​Error format

​HTTP status codes

​Common error codes

​Auto Refill codes

​Withdrawal verification codes

​Retry strategy

Error format

HTTP status codes

Common error codes

Auto Refill codes

Withdrawal verification codes

Retry strategy