Lỗi

Khi một request thất bại, API trả về mã trạng thái 4xx hoặc 5xx và một body JSON với code ổn định. Hãy rẽ nhánh theo code. Nội dung error dành cho con người và có thể thay đổi.

Định dạng

{
  "error": "This API key doesn't have the earnings:read scope.",
  "code": "insufficient_scope",
  "scope": "earnings:read"
}

Một vài lỗi có thêm trường riêng. Ví dụ, 409 upload_incomplete liệt kê các phần missing và wrong_size.

Lỗi mà mọi endpoint đều có thể trả về

404 not_found bao gồm cả trường hợp “không tồn tại” lẫn “thuộc về tài khoản khác”. API không bao giờ cho bạn biết một bản phát hành của người khác có tồn tại hay không.

Lỗi của từng endpoint cụ thể

Mỗi trang tham chiếu liệt kê lỗi của từng endpoint. Scope và lỗi có các lỗi dùng chung.

Lỗi kiểm tra dữ liệu

Một lỗi 400 invalid nêu vấn đề đầu tiên mà API tìm thấy:

{
  "error": "updated_since is an ISO date or time.",
  "code": "invalid",
  "field": "updated_since"
}

Mỗi lần chỉ báo một trường. Hãy sửa rồi gửi lại. Nếu bạn xây dựng biểu mẫu trên API, hãy hiển thị error cạnh ô nhập được nêu trong field.

Tệp DDEX thì khác. Một lô DDEX có vấn đề không phải là lỗi 400. Lần kiểm thử trả về 200 với mọi bước kiểm tra và một kết luận, còn một lần phân phối trả về 202 và báo vấn đề theo từng bản phát hành. Xem Phân phối DDEX.

Nên thử lại lỗi nào

• Thử lại 429 và 5xx, cùng các lỗi mạng như timeout và reset.
• Không thử lại các lỗi 4xx khác. Cùng một request sẽ nhận cùng một phản hồi. Hãy sửa request, key hoặc scope của key trước.

Với 429, hãy chờ số giây ghi trong Retry-After. Với 5xx, hãy chờ lâu hơn sau mỗi lần thử (1 giây, 2 giây, 4 giây…) và dừng lại sau vài lần. Xem Rate limit.

Thao tác đọc có thể thử lại an toàn. Hãy cân nhắc trước khi thử lại một thao tác ghi. Gửi lại POST /ddex sau khi mất phản hồi có thể đưa lô vào hàng đợi hai lần. Hãy kiểm tra GET /ddex trước.

Hàm xử lý lỗi cho Node

export class HillsError extends Error {
  constructor(status, body, headers) {
    super(body.error ?? `HTTP ${status}`);
    this.status = status;
    this.code = body.code;
    this.field = body.field;
    this.scope = body.scope;
    this.retryAfter = Number(headers.get("Retry-After")) || null;
  }
}

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

export async function hills(path, init = {}, tries = 4) {
  for (let i = 1; ; i++) {
    const res = await fetch("https://api.hillsmusic.com/v1" + path, {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
    });
    const body = await res.json().catch(() => ({}));
    if (res.ok) return body;
    const err = new HillsError(res.status, body, res.headers);
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || i >= tries) throw err;
    await sleep(err.retryAfter ? err.retryAfter * 1000 : 1000 * 2 ** (i - 1));
  }
}

try {
  await hills("/earnings");
} catch (err) {
  if (err.code === "insufficient_scope") console.error(`Add ${err.scope} to this key.`);
  else if (err.code === "api_not_in_plan") console.error("The plan doesn't include the API.");
  else throw err;
}

Với curl, thêm -w '%{http_code}' để xem mã trạng thái, hoặc -i để xem các header:

curl -i "https://api.hillsmusic.com/v1/releases/999999" \
  -H "Authorization: Bearer $HILLS_API_KEY"
# HTTP/2 404
# {"error":"…","code":"not_found"}