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.
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
| HTTP | Mã lỗi | Ý nghĩa & cách xử lý |
|---|---|---|
| 400 | INVALID_REQUEST | Thiế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 |
| 401 | UNAUTHORIZED | Sai Client ID/Secret khi lấy token — kiểm tra lại thông tin xác thực |
| 401 | TOKEN_EXPIRED | Access Token đã hết hạn (quá TTL) — gọi lại endpoint tạo token |
| 403 | DEVICE_NOT_OWNED | Thiết bị không thuộc tài khoản của bạn — kiểm tra lại hardwareId |
| 404 | DEVICE_NOT_FOUND | Không tìm thấy thiết bị với hardwareId này — kiểm tra số sê-ri in dưới đáy loa |
| 409 | DEVICE_NOT_PAIRED | Thiết bị chưa được ghép nối — hãy ghép nối trước khi bắn thông báo |
| 409 | OTP_INVALID | Mã OTP sai hoặc đã hết hạn — yêu cầu ghép nối lại để nhận OTP mới |
| 409 | DUPLICATE_REQUEST_ID | requestId đã tồn tại — hệ thống bỏ qua để tránh phát trùng |
| 422 | DEVICE_OFFLINE | Loa đang offline, không thể phát âm thanh — kiểm tra pin và kết nối mạng |
| 429 | RATE_LIMIT_EXCEEDED | Vượt giới hạn tần suất — chờ và thử lại theo header Retry-After |
| 500 | INTERNAL_ERROR | Lỗ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.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.
Bảng mã lỗi
| HTTP | Mã lỗi | Ý nghĩa & cách xử lý |
|---|---|---|
| 400 | INVALID_REQUEST | Thiế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 |
| 401 | UNAUTHORIZED | Sai Client ID/Secret khi lấy token — kiểm tra lại thông tin xác thực |
| 401 | TOKEN_EXPIRED | Access Token đã hết hạn (quá TTL) — gọi lại endpoint tạo token |
| 403 | DEVICE_NOT_OWNED | Thiết bị không thuộc tài khoản của bạn — kiểm tra lại hardwareId |
| 404 | DEVICE_NOT_FOUND | Không tìm thấy thiết bị với hardwareId này — kiểm tra số sê-ri in dưới đáy loa |
| 409 | DEVICE_NOT_PAIRED | Thiết bị chưa được ghép nối — hãy ghép nối trước khi bắn thông báo |
| 409 | OTP_INVALID | Mã OTP sai hoặc đã hết hạn — yêu cầu ghép nối lại để nhận OTP mới |
| 409 | DUPLICATE_REQUEST_ID | requestId đã tồn tại — hệ thống bỏ qua để tránh phát trùng |
| 422 | DEVICE_OFFLINE | Loa đang offline, không thể phát âm thanh — kiểm tra pin và kết nối mạng |
| 429 | RATE_LIMIT_EXCEEDED | Vượt giới hạn tần suất — chờ và thử lại theo header Retry-After |
| 500 | INTERNAL_ERROR | Lỗ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.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"
}