Mã lỗi, body lỗi và cách retry

HTTP/1.1 400 Bad Request

// GET /tracks/not-a-uuid
{ "error": "ID bài hát không hợp lệ." }

HTTP/1.1 400 Bad Request

// GET /tracks/by-ids?ids=<uuid>,abc
{
  "error": "Danh sách ids chứa UUID không hợp lệ.",
  "invalid_ids": ["abc"]
}

HTTP/1.1 400 Bad Request

// POST /webhooks với url sai
{
  "error": "Dữ liệu không hợp lệ.",
  "details": { "url": ["Phải là URL https hợp lệ."] }
}

HTTP/1.1 400 Bad Request

{
  "error": "Tham số truy vấn không hợp lệ.",
  "allowed_sort": ["newest", "oldest", "popular", "most_liked", "title_asc", "title_desc"],
  "pagination": {
    "limit": "Số nguyên từ 1 đến 100; mặc định 20.",
    "page": "Số nguyên từ 1 đến 5000; mặc định 1."
  },
  "filters": {
    "title": "Tìm một phần tên bài hát, tối đa 160 ký tự.",
    "genre": "Tìm một phần thể loại, tối đa 80 ký tự.",
    "artist": "Tìm một phần tên nghệ sĩ, tối đa 120 ký tự.",
    "artist_id": "UUID nghệ sĩ.",
    "q": "Tìm đồng thời trong title, artist và genre, tối đa 100 ký tự."
  }
}

HTTP/1.1 401 Unauthorized

// GET /me/usage khi thiếu header X-API-Key
{ "error": "Thiếu API key." }

HTTP/1.1 403 Forbidden

// Key sai, đã bị vô hiệu hóa, hoặc không có quyền cho endpoint này
{ "error": "API key không hợp lệ." }

HTTP/1.1 404 Not Found

{ "error": "Không tìm thấy bài hát." }

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{ "error": "Vượt giới hạn tần suất, vui lòng thử lại sau." }

HTTP/1.1 502 Bad Gateway
{ "error": "Không thể tải kho nhạc." }

HTTP/1.1 503 Service Unavailable
{ "error": "XuniBOX API chưa được cấu hình." }

HTTP/1.1 500 Internal Server Error
{ "error": "Không thể tải bài hát." }

class XuniBoxError extends Error {
  constructor(status, body, requestPath) {
    super(body?.error ?? `XuniBOX ${status}`);
    this.name = "XuniBoxError";
    this.status = status;
    this.path = requestPath;
    this.details = body?.details ?? null;
    this.invalidIds = body?.invalid_ids ?? null;
    this.retryable = status === 429 || status >= 500;
    this.retryAfter = null;
  }
}

export async function xunibox(path, init = {}) {
  const res = await fetch(`https://xunibox.vn/api/public${path}`, {
    ...init,
    headers: { Accept: "application/json", ...init.headers }
  });

  if (res.ok) return res.status === 204 ? null : res.json();

  // Body lỗi LUÔN là JSON, nhưng vẫn phòng trường hợp proxy trả HTML.
  const body = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
  const err = new XuniBoxError(res.status, body, path);
  err.retryAfter = Number(res.headers.get("Retry-After")) || null;
  throw err;
}

async function xuniboxFetch(path, { retries = 3 } = {}) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const res = await fetch(`https://xunibox.vn/api/public${path}`, {
      headers: { "X-API-Key": process.env.XUNIBOX_API_KEY, Accept: "application/json" }
    });

    if (res.ok) return res.json();

    // 4xx là lỗi phía bạn — retry cũng vô ích, trừ 429.
    if (res.status !== 429 && res.status < 500) {
      const body = await res.json().catch(() => ({}));
      throw new Error(body.error ?? `XuniBOX ${res.status}`);
    }

    if (attempt === retries) throw new Error(`XuniBOX ${res.status} sau ${retries} lần thử`);

    const retryAfter = Number(res.headers.get("Retry-After"));
    const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : 2 ** attempt * 500 + Math.random() * 250;   // backoff + jitter

    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }
}