錯誤碼與處理
理解和處理 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 不重試（請求錯誤）