# Scope và lỗi

> Các scope mà một key có thể có, các lỗi mà mọi endpoint có thể trả về, và rate limit.

<!-- Generated from openapi/hills-v1.json by scripts/api-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

<a id="scopes"></a>

## Scope

Mỗi key có scope riêng, được chọn khi tạo key.

| Scope | Cho phép làm gì |
| --- | --- |
| `members:read` | Liệt kê nghệ sĩ và hãng đĩa của bạn. |
| `members:write` | Mời nghệ sĩ và hãng đĩa mới vào tài khoản của bạn. |
| `catalog:read` | Bản phát hành, track và việc phân phối chúng đến các nền tảng. |
| `earnings:read` | Doanh thu theo tháng, bản phát hành hoặc nền tảng. |
| `payouts:read` | Số dư và các yêu cầu rút tiền của bạn. |
| `links:read` | Smart link và pre-save cùng số liệu thống kê. |
| `ddex:write` | Phân phối các lô DDEX ERN (zip; khuyến nghị 4.3.2 hoặc 3.8.2, chấp nhận 4.3/4.2/4.1/3.8.1/3.8/3.7) để tạo bản phát hành nháp, và đọc trạng thái của chúng. |
| `ddex:validate` | Kiểm thử các message và lô ERN (mọi phiên bản được chấp nhận) với mọi bước kiểm tra như một lần phân phối; không có gì được tạo ra. |
| `webhooks:read` | Liệt kê endpoint webhook của bạn và những gì đã được gửi đến chúng. |
| `webhooks:write` | Tạo, sửa và xóa endpoint webhook, đổi secret, gửi sự kiện test và gửi lại các lần gửi. |

<a id="errors"></a>

## Lỗi

Lỗi trả về `{ "error": "…", "code": "…" }` (thêm `field` khi dữ liệu đầu vào không hợp lệ và `scope` khi thiếu scope).

| Mã trạng thái | Code | Ý nghĩa |
| --- | --- | --- |
| 400 | `invalid` | Một parameter bị sai; field cho biết parameter nào. |
| 401 | `unauthenticated` | Không có header Authorization: Bearer. |
| 401 | `invalid_key` | Key không tồn tại. |
| 401 | `key_revoked / key_expired` | Key đã bị thu hồi hoặc đã hết hạn. Hãy tạo key mới. |
| 401 | `test_keys_retired` | Một key test (hm_test_…): đã ngừng sử dụng từ 12/10/2026. Hãy dùng key production (hm_live_…) và kiểm thử bằng POST /ddex/validate. |
| 403 | `insufficient_scope` | Key thiếu scope mà endpoint này cần; scope cho biết scope nào. |
| 403 | `account_inactive` | Tài khoản của bạn không hoạt động. |
| 403 | `api_not_in_plan` | Gói của bạn không bao gồm API. API đi kèm các gói Enterprise và Custom. |
| 404 | `not_found` | Không có endpoint này, hoặc đối tượng không thuộc về bạn. |
| 429 | `rate_limited` | Số request trong một phút trên key này vượt mức gói của bạn cho phép (X-RateLimit-Limit). Chờ số giây ghi trong Retry-After. |

<a id="rate-limits"></a>

## Rate limit

Số request mỗi phút cho mỗi key tùy theo gói của bạn (120 ở gói Enterprise, đặt theo khối lượng của bạn ở gói Custom); `X-RateLimit-Limit` cho biết giới hạn của bạn, mọi phản hồi đều mang `X-RateLimit-Remaining`, và phản hồi 429 mang `Retry-After` (tính bằng giây).

Nguồn: https://developer.hillsmusic.com/vi/reference/scopes-and-errors/