错误码与处理
理解和处理 API 错误
错误响应格式
所有错误响应使用统一格式：
{
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message",
"details": "Additional context (optional)"
}
}💡 使用 error.code 作为稳定的分支条件（message 可能变化）
HTTP 状态码
200 OK
请求成功
201 Created
资源创建成功
400 Bad Request
请求参数错误
{
"code": "INVALID_REQUEST",
"message": "Invalid request format"
}401 Unauthorized
未授权或 API Key 无效
{
"code": "UNAUTHORIZED",
"message": "Invalid or expired API key"
}403 Forbidden
账户余额不足或权限不足
{
"code": "INSUFFICIENT_BALANCE",
"message": "Account balance is insufficient"
}404 Not Found
资源不存在
{
"code": "ORDER_NOT_FOUND",
"message": "Order not found"
}409 Conflict
资源冲突
{
"code": "ADDRESS_EXISTS",
"message": "Address already exists"
}429 Too Many Requests
API Key 请求频率超限
{
"code": "RATE_LIMITED",
"message": "Rate limit exceeded"
}500 Internal Server Error
服务器内部错误
{
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}503 Service Unavailable
服务暂时不可用（维护中）
{
"code": "SERVICE_UNAVAILABLE",
"message": "Service is temporarily unavailable"
}常见错误码
| Error Code | Status | Description | Solution |
|---|---|---|---|
| UNAUTHORIZED | 401 | API Key 无效、已过期或已被撤销 | 检查 API Key 是否正确，必要时重新创建 |
| INSUFFICIENT_BALANCE | 403 | 账户余额不足 | 充值账户余额 |
| INVALID_ADDRESS | 400 | TRON 地址格式无效 | 检查地址是否为有效的 TRON 地址（以 T 开头） |
| INVALID_ENERGY_AMOUNT | 400 | 能量数量无效 | 能量数量必须是正整数，推荐 65000 用于 USDT 转账 |
| INVALID_DURATION | 400 | 租赁时长无效 | 使用有效的时长：1H, 1D, 3D, 7D, 14D, 30D |
| ORDER_NOT_FOUND | 404 | 订单不存在 | 检查订单 ID 是否正确 |
| ADDRESS_EXISTS | 409 | 地址已存在 | 检查是否已添加该地址，或使用现有地址 |
| RATE_LIMITED | 429 | API Key 请求频率超限（当前仅对 POST /v1/wallet/recharges 生效） | 实现指数退避重试，或降低调用频率 |
该怎么做
| Error | Handling |
|---|---|
| 401 UNAUTHORIZED | 检查/轮换 API Key |
| 403 INSUFFICIENT_BALANCE | 充值或降低请求金额 |
| 409 ADDRESS_EXISTS | 改为查询/幂等处理 |
| 429 RATE_LIMITED | 退避重试（如存在 Retry-After 则遵循，否则指数退避） |
| 5xx | 重试 + 记录请求上下文 |
重试要点
- • max retries: 3
- • backoff: 指数退避（1s, 2s, 4s...）
- • 只重试 429/5xx
- • 4xx 不重试（请求错误）