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.
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. |
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. |
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).