Mã lỗi API Loa SoundBox

Bảng mã lỗi của Loa thông báo HiTechCloud Pay: toàn bộ mã HTTP và mã lỗi nghiệp vụ kèm nguyên nhân và cách xử lý từng trường hợp.

Xem Markdown

Mọi phản hồi lỗi của Speaker API đều trả về theo cấu trúc thống nhất gồm code, message (tiếng Việt) và error (mã kỹ thuật). Dùng trường error để xử lý theo chương trình.

Cấu trúc phản hồi lỗi
{
  "code": 404,
  "message": "Không tìm thấy thiết bị loa với mã phần cứng này",
  "error": "DEVICE_NOT_FOUND"
}

Bảng mã lỗi

HTTPMã lỗiÝ nghĩa & cách xử lý
400INVALID_REQUESTThiếu tham số bắt buộc hoặc sai định dạng — kiểm tra lại thân yêu cầu JSON
401UNAUTHORIZEDSai Client ID/Secret khi lấy token — kiểm tra lại thông tin xác thực
401TOKEN_EXPIREDAccess Token đã hết hạn (quá TTL) — gọi lại endpoint tạo token
403DEVICE_NOT_OWNEDThiết bị không thuộc tài khoản của bạn — kiểm tra lại hardwareId
404DEVICE_NOT_FOUNDKhông tìm thấy thiết bị với hardwareId này — kiểm tra số sê-ri in dưới đáy loa
409DEVICE_NOT_PAIREDThiết bị chưa được ghép nối — hãy ghép nối trước khi bắn thông báo
409OTP_INVALIDMã OTP sai hoặc đã hết hạn — yêu cầu ghép nối lại để nhận OTP mới
409DUPLICATE_REQUEST_IDrequestId đã tồn tại — hệ thống bỏ qua để tránh phát trùng
422DEVICE_OFFLINELoa đang offline, không thể phát âm thanh — kiểm tra pin và kết nối mạng
429RATE_LIMIT_EXCEEDEDVượt giới hạn tần suất — chờ và thử lại theo header Retry-After
500INTERNAL_ERRORLỗi hệ thống nội bộ — thử lại sau, nếu lặp lại hãy liên hệ hỗ trợ
Khi gặp lỗi TOKEN_EXPIRED, hãy tự động lấy token mới và gọi lại yêu cầu một lần duy nhất để tránh vòng lặp vô hạn.