Hạn mức & header RateLimit

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600
ETag: "a1b2c3d4e5f6"
X-Total-Count: 248
X-Page: 1
X-Limit: 20
X-Offset: 0

# Mọi endpoint dữ liệu đều BẮT BUỘC header X-API-Key và tính vào hạn mức:
#   /tracks  /tracks/:id  /tracks/by-ids  /tracks/:id/audio-url
#   /tracks/:id/license  /tracks/:id/similar  /tracks/:id/waveform
#   /tracks/waveforms  /search  /search/suggest  /trending  /licenses
#   /artists  /artists/:id/tracks  /genres
#
# Chỉ nhóm hạ tầng dưới đây là KHÔNG cần key (vẫn giới hạn theo IP):
#   /health  /healthz  /readyz  /status  /metrics
#   /openapi.json  /openapi.v1.json  /tracks/:id/cover
# Gọi bao nhiêu lần cũng được — nhưng hãy cache phía bạn và đừng poll
# dưới 10 giây một lần. XuniBOX có thể bật hạn mức cho nhóm này trong
# tương lai, nên client của bạn vẫn nên xử lý được 429.

/**
 * Bộ gọi API tự điều tiết: đọc header còn lại và tự chờ khi sắp chạm trần.
 * Dùng chung một instance cho toàn bộ backend của bạn.
 */
class XuniBoxClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.remaining = Infinity;
    this.resetAfterMs = 0;
    this.resetAt = 0;
  }

  async request(path, init = {}) {
    // Nếu lần trước báo đã hết hạn mức thì ngủ tới lúc reset.
    if (this.remaining <= 0 && Date.now() < this.resetAt) {
      await new Promise((r) => setTimeout(r, this.resetAt - Date.now()));
    }

    const res = await fetch(`https://xunibox.vn/api/public${path}`, {
      ...init,
      headers: { ...init.headers, "X-API-Key": this.apiKey, Accept: "application/json" },
    });

    // Cập nhật trạng thái hạn mức từ header mỗi phản hồi.
    const remaining = res.headers.get("X-RateLimit-Remaining");
    const resetAfter = res.headers.get("X-RateLimit-Reset-After");
    if (remaining !== null) this.remaining = Number(remaining);
    if (resetAfter !== null) this.resetAt = Date.now() + Number(resetAfter) * 1000;

    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") ?? 5) * 1000;
      await new Promise((r) => setTimeout(r, wait));
      return this.request(path, init); // thử lại đúng một vòng sau khi chờ
    }

    if (!res.ok) throw new Error(`XuniBOX ${res.status}: ${await res.text()}`);
    return res.json();
  }
}

const xunibox = new XuniBoxClient(process.env.XUNIBOX_API_KEY);
const { data } = await xunibox.request("/tracks?limit=20");

<?php
// Laravel / PHP thuần: đọc header hạn mức và tôn trọng Retry-After.
function xuniboxGet(string $path, array $query = []): array
{
    $url = 'https://xunibox.vn/api/public' . $path . '?' . http_build_query($query);

    for ($attempt = 1; $attempt <= 3; $attempt++) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HEADER         => true,
            CURLOPT_HTTPHEADER     => [
                'X-API-Key: ' . env('XUNIBOX_API_KEY'),
                'Accept: application/json',
            ],
        ]);
        $raw       = curl_exec($ch);
        $status    = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $headerLen = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        $headers   = substr($raw, 0, $headerLen);
        $body      = substr($raw, $headerLen);
        curl_close($ch);

        if ($status === 429) {
            preg_match('/retry-after:\s*(\d+)/i', $headers, $m);
            sleep((int) ($m[1] ?? 5));
            continue;
        }

        if ($status >= 500) { sleep(2 ** $attempt); continue; }

        return json_decode($body, true);
    }

    throw new RuntimeException('XuniBOX API không phản hồi sau 3 lần thử.');
}

import os, time, requests

BASE = "https://xunibox.vn/api/public"
SESSION = requests.Session()
SESSION.headers.update({"X-API-Key": os.environ["XUNIBOX_API_KEY"], "Accept": "application/json"})

def xunibox_get(path: str, **params):
    for attempt in range(3):
        res = SESSION.get(f"{BASE}{path}", params=params, timeout=10)

        remaining = int(res.headers.get("X-RateLimit-Remaining", 999))
        if remaining <= 2:                       # sắp chạm trần, tự giãn nhịp
            time.sleep(int(res.headers.get("X-RateLimit-Reset-After", 1)))

        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", 5)))
            continue
        if res.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        res.raise_for_status()
        return res.json()

    raise RuntimeError("XuniBOX API không phản hồi sau 3 lần thử.")

// Ước lượng hạn mức cần thiết cho ứng dụng của bạn.
//
//   requests/phút = (số người mở bộ chọn nhạc mỗi phút)
//                 x (số request mỗi phiên: 1 danh sách + 1 genres + n lần tìm kiếm)
//
// Ví dụ: 300 người/phút mở bộ chọn nhạc, mỗi người gọi trung bình 4 request
//        => 1.200 req/phút, vượt xa mức mặc định 60.
//
// Cách xử lý đúng: KHÔNG xin hạn mức 1.200. Hãy cache ở backend của bạn.

// Backend của bạn (Node) — cache danh sách 5 phút, phục vụ mọi người dùng.
const cache = new Map(); // key -> { at, body }
const TTL_MS = 5 * 60 * 1000;

export async function getTracks(query) {
  const key = new URLSearchParams(query).toString();
  const hit = cache.get(key);
  if (hit && Date.now() - hit.at < TTL_MS) return hit.body;

  const res = await fetch(`https://xunibox.vn/api/public/tracks?${key}`, {
    headers: { "X-API-Key": process.env.XUNIBOX_API_KEY },
  });
  const body = await res.json();
  cache.set(key, { at: Date.now(), body });
  return body;
}

// Với cache 5 phút, 300 người/phút chỉ tốn khoảng 1-2 request/phút tới XuniBOX.