Giới hạn tốc độ

Để bảo vệ hệ thống, API giới hạn số yêu cầu trong một khoảng thời gian cho mỗi API key. Phản hồi của yêu cầu dùng API key luôn kèm ba header cho biết bạn còn bao nhiêu lượt.

Các header

Header	Ý nghĩa
RateLimit-Limit	Số yêu cầu tối đa trong cửa sổ hiện tại.
RateLimit-Remaining	Số yêu cầu còn lại trong cửa sổ hiện tại.
RateLimit-Reset	Cho biết khi nào cửa sổ làm mới. Đơn vị chính xác ghi trong Scalar; ví dụ bên dưới giả định là số giây còn lại.

Hạn mức áp dụng cho từng khoá hiển thị trên thẻ API key trong ứng dụng và trong chính các header này; đừng mã hoá cứng một con số trong tích hợp của bạn.

Cách điều tiết

• Đọc RateLimit-Remaining và RateLimit-Reset sau mỗi phản hồi. Khi Remaining về 0, tạm dừng cho tới khi cửa sổ làm mới.
• Dùng phân trang lớn (limit=200) khi đồng bộ hàng loạt để giảm số yêu cầu; xem Phân trang.
• Ưu tiên webhook thay vì hỏi liên tục (polling): hoadon.pro gửi sự kiện tới bạn khi có thay đổi; xem Webhook.
• Thử lại có chờ luỹ thừa khi gặp lỗi; với thao tác ghi dùng Idempotency.

async function throttled(url, options) {
  const res = await fetch(url, options);
  const remaining = Number(res.headers.get('RateLimit-Remaining'));
  const reset = Number(res.headers.get('RateLimit-Reset'));
  if (remaining === 0 && reset > 0) {
    await new Promise((resolve) => setTimeout(resolve, reset * 1000));
  }
  return res;
}