Rate limit

Mỗi API key được gửi một số request nhất định mỗi phút. Con số này phụ thuộc vào gói của tài khoản khách hàng.

Giới hạn theo gói

Giới hạn tính theo key, không theo tài khoản. Mọi request gửi bằng một key hợp lệ đều được tính, kể cả request thất bại như 404 hay 403 insufficient_scope.

Cửa sổ tính là một phút cố định. Cửa sổ bắt đầu từ request đầu tiên của key và đặt lại sau 60 giây. Đây không phải trung bình trượt, nên một loạt request dồn dập ở đầu cửa sổ có thể dùng hết hạn mức của cả phút.

MCP server có giới hạn riêng: 120 lệnh gọi mỗi phút cho mỗi ứng dụng đã kết nối. Xem MCP server.

Header

Mọi phản hồi đều mang:

Phản hồi 429 còn mang thêm:

GET /ping hiển thị cùng các con số này trong body, dưới plan.rate và rate_limit:

curl "https://api.hillsmusic.com/v1/ping" \
  -H "Authorization: Bearer $HILLS_API_KEY"

{
  "ok": true,
  "plan": { "included": true, "plan": "enterprise", "rate": 120 },
  "rate_limit": { "limit": 120, "remaining": 119 }
}

Khi bạn vượt giới hạn

Khi vượt giới hạn, API trả về 429 trước khi đọc body của request:

HTTP/2 429
Retry-After: 23
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{"error":"Too many requests: at most 120 a minute per key.","code":"rate_limited"}

Hãy chờ Retry-After giây, rồi gửi lại request. Request bị từ chối chưa được xử lý chút nào, nên gửi lại là an toàn, kể cả với thao tác ghi.

POST /ddex/validate cũng có thể trả về 429 busy khi có quá nhiều lần kiểm thử chạy cùng lúc. Đó không phải giới hạn mỗi phút của bạn. Hãy chờ vài giây rồi thử lại.

Backoff trong Node

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function hills(path, init = {}) {
  for (let attempt = 1; attempt <= 5; attempt++) {
    const res = await fetch("https://api.hillsmusic.com/v1" + path, {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
    });
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await sleep(wait * 1000);
  }
  throw new Error("Still rate limited after 5 tries");
}

Tốt hơn là tự điều tiết tốc độ

Tốt nhất là đừng chạm đến giới hạn. Hãy đọc X-RateLimit-Remaining và giảm tốc khi giá trị này xuống thấp:

let remaining = Infinity;

async function paced(path) {
  if (remaining < 5) await sleep(5000); // close to the limit: wait for the window to reset
  const res = await hills(path);
  remaining = Number(res.headers.get("X-RateLimit-Remaining") ?? Infinity);
  return res;
}

Với curl trong một vòng lặp shell, hãy nghỉ nửa giây giữa các lệnh gọi để giữ dưới 120 request mỗi phút:

for id in 812 813 814; do
  curl -s "https://api.hillsmusic.com/v1/releases/$id" \
    -H "Authorization: Bearer $HILLS_API_KEY"
  sleep 0.5
done

Gửi ít request hơn

• Dùng trang lớn. GET /releases?limit=100 trả về 100 bản phát hành cho một request thay vì 50.
• Chỉ đồng bộ phần thay đổi. GET /releases?updated_since=<last run> chỉ trả về các bản phát hành đã thay đổi kể từ thời điểm đó.
• Dùng webhook thay vì polling. Đăng ký release.live hoặc delivery.store_status_changed thay vì vài phút lại kiểm tra từng bản phát hành. Xem Webhook.
• Poll các lần phân phối DDEX chậm thôi. Một lần phân phối mất từ vài giây đến vài phút. Hãy poll GET /ddex/{id} mỗi 10–30 giây, hoặc đăng ký ddex.import.imported.
• Cache những gì ít thay đổi, như danh sách thành viên và doanh thu theo tháng.

Phân tải qua nhiều key

Mỗi key có giới hạn riêng. Dùng một key cho mỗi hệ thống (một cho việc đồng bộ ERP, một cho website) giúp một job bận rộn không chiếm hết hạn mức của các job khác. Đừng tạo thêm key chỉ để lách giới hạn. Nếu cần nhiều hơn, hãy hỏi người phụ trách của bạn tại HILLS Music về gói Custom, nơi giới hạn được đặt theo khối lượng của bạn.