Error Codes

When an API call fails, the response contains a non-zero code and a human-readable error message.

Error response format

{
  "code": 60,
  "key": "address_from",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Invalid TRON address"
}

Field	Description
code	Non-zero integer error code.
key	Name of the field that caused the error, when applicable. Empty string otherwise.
request_id	Unique identifier of the request. Include when contacting support.
error	Human-readable description of the error.

HTTP status codes

HTTP Status	Meaning
200	Request succeeded (code: 0) or application-level error (code: non-zero).
429	Rate limit exceeded — 1 request/second/IP on /v1/orders* endpoints.
422	Unprocessable request — validation failed (also returned as code: non-zero in body).
500	Internal server error — unexpected failure on our side.

Common error cases

Situation	Likely cause
Invalid address_from or address_to	Not a valid TRON address (must start with T, 34 chars).
duration not equal to 1	Only 1-hour rentals are supported.
Both energy and bandwidth are 0	At least one resource must be requested.
energy or bandwidth out of bounds	The requested amount is below the minimum or above the maximum for this project.
Duplicate active order	An active order for the same address_from + address_to pair already exists in new status.
order_id not found	The order_id passed to check or cancel does not exist.
Rate limit exceeded	You are sending more than 1 request/second from the same IP. Back off and retry.
referral_code too long	The referral_code string exceeds 64 characters.

Handling errors

1. Always check code in the response body — HTTP 200 does not guarantee success.
2. Log request_id alongside any error for debugging.
3. For HTTP 429, implement exponential back-off before retrying.
4. For duplicate active order, use Check Order to retrieve the existing order instead of creating a new one.