Error Codes - API Documentation

Error Response Format

All error responses use a unified format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": "Additional context (optional)"
  }
}

💡 Use error.code as a stable branching condition (message may change)

HTTP Status Codes

200 OK

Request successful

200

201 Created

Resource created successfully

201

400 Bad Request

Request parameters are invalid

400

{
  "code": "INVALID_REQUEST",
  "message": "Invalid request format"
}

401 Unauthorized

Unauthorized or invalid API Key

401

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired API key"
}

403 Forbidden

Insufficient account balance or permissions

403

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Account balance is insufficient"
}

404 Not Found

Resource not found

404

{
  "code": "ORDER_NOT_FOUND",
  "message": "Order not found"
}

409 Conflict

Resource conflict

409

{
  "code": "ADDRESS_EXISTS",
  "message": "Address already exists"
}

429 Too Many Requests

API Key request rate limit exceeded

429

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded"
}

500 Internal Server Error

Internal server error

500

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred"
}

503 Service Unavailable

Service temporarily unavailable (under maintenance)

503

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service is temporarily unavailable"
}

Common Error Codes

Error Code	Status	Description	Solution
UNAUTHORIZED	401	API Key is invalid, expired, or revoked	Check if the API Key is correct, create a new one if necessary
INSUFFICIENT_BALANCE	403	Insufficient account balance	Recharge account balance
INVALID_ADDRESS	400	Invalid TRON address format	Check if the address is a valid TRON address (starts with T)
INVALID_ENERGY_AMOUNT	400	Invalid energy amount	Energy amount must be a positive integer, recommended 65000 for USDT transfers
INVALID_DURATION	400	Invalid rental duration	Use valid durations: 1H, 1D, 3D, 7D, 14D, 30D
ORDER_NOT_FOUND	404	Order does not exist	Check if the order ID is correct
ADDRESS_EXISTS	409	Address already exists	Check if the address has already been added, or use the existing address
RATE_LIMITED	429	API Key request rate limit exceeded (currently only applies to POST /v1/wallet/recharges)	Implement exponential backoff retry, or reduce call frequency

How to Handle

Error	Handling
401 UNAUTHORIZED	Check/rotate API Key
403 INSUFFICIENT_BALANCE	Recharge or reduce request amount
409 ADDRESS_EXISTS	Switch to query/idempotent handling
429 RATE_LIMITED	Backoff retry (follow Retry-After if present, otherwise exponential backoff)
5xx	Retry + log request context

Retry Guidelines

• max retries: 3
• backoff: exponential (1s, 2s, 4s...)
• only retry 429/5xx
• do not retry 4xx (client errors)

Error Codes & Handling