Error codes

Failures return an HTTP error status and a stable envelope:

{
  "error": {
    "code": "INVALID_DURATION",
    "message": "Unsupported duration",
    "details": null
  },
  "request_id": "…"
}

The code is stable and safe to match on; message is human-readable and may change.

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Missing or invalid signing headers, bad signature, expired timestamp, replayed nonce, or an unknown/revoked API key.
`FORBIDDEN`	403	Authenticated but not permitted.
`INVALID_REQUEST`	400	Malformed or failed-validation request.
`INVALID_ADDRESS`	400	`target_address` is not a valid TRON address.
`INVALID_DURATION`	400	`duration_minutes` is not in the allowed catalog.
`NOT_FOUND`	404	Resource not found.
`ORDER_NOT_FOUND`	404	Quote or order not found, or not owned by your account.
`QUOTE_EXPIRED`	409	The quote is no longer open or has expired.
`INSUFFICIENT_BALANCE`	402	Prepaid balance cannot cover the order.
`IDEMPOTENCY_CONFLICT`	409	Idempotency key reused with a different payload.
`RATE_LIMITED`	429	Too many requests; slow down and retry.
`SERVICE_UNAVAILABLE`	503	The service is unavailable; retry later.
`INTERNAL_ERROR`	500	Unexpected server error.

Retry guidance

Safe to retry (with the same idempotency key): SERVICE_UNAVAILABLE, RATE_LIMITED, and network-level failures.
Do not blindly retry 4xx errors without fixing the request first.