Giới hạn tần suất gọi API Loa
Giới hạn tần suất của API Loa thông báo HiTechCloud Pay: hạn mức số yêu cầu mỗi phút, các header liên quan và cách xử lý khi bị giới hạn.
Để đảm bảo chất lượng dịch vụ cho tất cả cửa hàng, Speaker API áp dụng giới hạn tần suất (rate limit) theo từng cặp Client ID và theo từng thiết bị loa. Vượt ngưỡng, server trả về mã 429 RATE_LIMIT_EXCEEDED.
Hạn mức theo endpoint
| Nhóm endpoint | Giới hạn | Phạm vi |
|---|---|---|
| Tạo Access Token | 30 lượt / phút | Theo Client ID |
| Kiểm tra & liên kết thiết bị | 60 lượt / phút | Theo Client ID |
| Bắn thông báo (notify) | 10 lượt / phút / thiết bị | Theo hardwareId |
| Tra cứu trạng thái & danh sách | 120 lượt / phút | Theo Client ID |
Header phản hồi về hạn mức
| Header | Ý nghĩa |
|---|---|
X-RateLimit-Limit | Tổng số lượt cho phép trong cửa sổ thời gian |
X-RateLimit-Remaining | Số lượt còn lại trong cửa sổ hiện tại |
X-RateLimit-Reset | Thời điểm (epoch giây) hạn mức được đặt lại |
Retry-After | Số giây cần chờ trước khi thử lại (chỉ xuất hiện khi bị 429) |
Phản hồi khi vượt giới hạn (429)
{
"code": 429,
"message": "Bạn đã gọi quá nhanh, vui lòng thử lại sau",
"error": "RATE_LIMIT_EXCEEDED",
"retryAfter": 12
}Hãy triển khai cơ chế chờ-rồi-thử-lại (exponential backoff) dựa trên header
Retry-After. Tránh gửi lại ngay lập tức vì sẽ tiếp tục bị từ chối.Giới hạn 10 lượt notify/phút/thiết bị là đủ cho hoạt động bán hàng thực tế. Nếu cần hạn mức cao hơn, hãy liên hệ đội ngũ HiTechCloud để nâng cấp gói.
Để đảm bảo chất lượng dịch vụ cho tất cả cửa hàng, Speaker API áp dụng giới hạn tần suất (rate limit) theo từng cặp Client ID và theo từng thiết bị loa. Vượt ngưỡng, server trả về mã 429 RATE_LIMIT_EXCEEDED.
Hạn mức theo endpoint
| Nhóm endpoint | Giới hạn | Phạm vi |
|---|---|---|
| Tạo Access Token | 30 lượt / phút | Theo Client ID |
| Kiểm tra & liên kết thiết bị | 60 lượt / phút | Theo Client ID |
| Bắn thông báo (notify) | 10 lượt / phút / thiết bị | Theo hardwareId |
| Tra cứu trạng thái & danh sách | 120 lượt / phút | Theo Client ID |
Header phản hồi về hạn mức
| Header | Ý nghĩa |
|---|---|
X-RateLimit-Limit | Tổng số lượt cho phép trong cửa sổ thời gian |
X-RateLimit-Remaining | Số lượt còn lại trong cửa sổ hiện tại |
X-RateLimit-Reset | Thời điểm (epoch giây) hạn mức được đặt lại |
Retry-After | Số giây cần chờ trước khi thử lại (chỉ xuất hiện khi bị 429) |
Hãy triển khai cơ chế chờ-rồi-thử-lại (exponential backoff) dựa trên header
Retry-After. Tránh gửi lại ngay lập tức vì sẽ tiếp tục bị từ chối.Giới hạn 10 lượt notify/phút/thiết bị là đủ cho hoạt động bán hàng thực tế. Nếu cần hạn mức cao hơn, hãy liên hệ đội ngũ HiTechCloud để nâng cấp gói.
Phản hồi khi vượt giới hạn (429)
{
"code": 429,
"message": "Bạn đã gọi quá nhanh, vui lòng thử lại sau",
"error": "RATE_LIMIT_EXCEEDED",
"retryAfter": 12
}