Mã lỗi - Tài liệu API

Định dạng phản hồi lỗi

Tất cả các phản hồi lỗi sử dụng định dạng thống nhất:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Thông báo lỗi dễ đọc",
    "details": "Ngữ cảnh bổ sung (tùy chọn)"
  }
}

💡 Sử dụng error.code làm điều kiện phân nhánh ổn định (message có thể thay đổi)

Mã trạng thái HTTP

200 OK

Yêu cầu thành công

200

201 Created

Tạo tài nguyên thành công

201

400 Bad Request

Tham số yêu cầu không hợp lệ

400

{
  "code": "INVALID_REQUEST",
  "message": "Định dạng yêu cầu không hợp lệ"
}

401 Unauthorized

Chưa xác thực hoặc API Key không hợp lệ

401

{
  "code": "UNAUTHORIZED",
  "message": "API key không hợp lệ hoặc đã hết hạn"
}

403 Forbidden

Số dư tài khoản không đủ hoặc không có quyền

403

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Số dư tài khoản không đủ"
}

404 Not Found

Không tìm thấy tài nguyên

404

{
  "code": "ORDER_NOT_FOUND",
  "message": "Không tìm thấy đơn hàng"
}

409 Conflict

Xung đột tài nguyên

409

{
  "code": "ADDRESS_EXISTS",
  "message": "Địa chỉ đã tồn tại"
}

429 Too Many Requests

Vượt quá giới hạn tốc độ yêu cầu API Key

429

{
  "code": "RATE_LIMITED",
  "message": "Đã vượt quá giới hạn tốc độ"
}

500 Internal Server Error

Lỗi máy chủ nội bộ

500

{
  "code": "INTERNAL_ERROR",
  "message": "Đã xảy ra lỗi không mong muốn"
}

503 Service Unavailable

Dịch vụ tạm thời không khả dụng (đang bảo trì)

503

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Dịch vụ tạm thời không khả dụng"
}

Mã lỗi phổ biến

Error Code	Status	Description	Solution
UNAUTHORIZED	401	API Key không hợp lệ, đã hết hạn hoặc bị thu hồi	Kiểm tra xem API Key có chính xác không, tạo mới nếu cần thiết
INSUFFICIENT_BALANCE	403	Số dư tài khoản không đủ	Nạp tiền vào tài khoản
INVALID_ADDRESS	400	Định dạng địa chỉ TRON không hợp lệ	Kiểm tra xem địa chỉ có phải là địa chỉ TRON hợp lệ không (bắt đầu bằng T)
INVALID_ENERGY_AMOUNT	400	Số lượng năng lượng không hợp lệ	Số lượng năng lượng phải là số nguyên dương, khuyến nghị 65000 cho chuyển USDT
INVALID_DURATION	400	Thời hạn thuê không hợp lệ	Sử dụng thời hạn hợp lệ: 1H, 1D, 3D, 7D, 14D, 30D
ORDER_NOT_FOUND	404	Đơn hàng không tồn tại	Kiểm tra xem ID đơn hàng có chính xác không
ADDRESS_EXISTS	409	Địa chỉ đã tồn tại	Kiểm tra xem địa chỉ đã được thêm chưa, hoặc sử dụng địa chỉ hiện có
RATE_LIMITED	429	Vượt quá giới hạn tốc độ yêu cầu API Key (hiện chỉ áp dụng cho POST /v1/wallet/recharges)	Triển khai thử lại backoff theo cấp số nhân, hoặc giảm tần suất gọi

Cách xử lý

Error	Handling
401 UNAUTHORIZED	Kiểm tra/luân chuyển API Key
403 INSUFFICIENT_BALANCE	Nạp tiền hoặc giảm số lượng yêu cầu
409 ADDRESS_EXISTS	Chuyển sang truy vấn/xử lý idempotent
429 RATE_LIMITED	Thử lại backoff (tuân theo Retry-After nếu có, nếu không thì backoff theo cấp số nhân)
5xx	Thử lại + ghi log ngữ cảnh yêu cầu

Hướng dẫn thử lại

• số lần thử lại tối đa: 3
• backoff: theo cấp số nhân (1s, 2s, 4s...)
• chỉ thử lại 429/5xx
• không thử lại 4xx (lỗi phía client)

Mã lỗi & Xử lý