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.

Xem Markdown

Để đả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 endpointGiới hạnPhạm vi
Tạo Access Token30 lượt / phútTheo Client ID
Kiểm tra & liên kết thiết bị60 lượt / phútTheo 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ách120 lượt / phútTheo Client ID

Header phản hồi về hạn mức

HeaderÝ nghĩa
X-RateLimit-LimitTổng số lượt cho phép trong cửa sổ thời gian
X-RateLimit-RemainingSố lượt còn lại trong cửa sổ hiện tại
X-RateLimit-ResetThời điểm (epoch giây) hạn mức được đặt lại
Retry-AfterSố 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.