Scopes and errors
The scopes a key can have, the errors every endpoint can answer, and the rate limit.
Scopes
Each key has its own scopes, chosen when it is made.
| Scope | What it allows |
|---|---|
members:read |
List your artists and labels. |
members:write |
Invite new artists and labels under your account. |
catalog:read |
Releases, tracks and their delivery to stores. |
earnings:read |
Revenue by month, release or store. |
payouts:read |
Your balance and withdrawal requests. |
links:read |
Smartlinks and pre-saves with their stats. |
ddex:write |
Deliver DDEX ERN batches (zip; 4.3 recommended, 4.2/4.1/3.8.x/3.7 accepted) that become draft releases, and read their status. |
ddex:validate |
Dry-run ERN messages and batches (any accepted version); nothing is imported. |
Errors
Errors answer { "error": "…", "code": "…" } (plus field for invalid input and scope for a missing scope).
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid |
A parameter is wrong; field names it. |
| 401 | unauthenticated |
No Authorization: Bearer header. |
| 401 | invalid_key |
The key doesn’t exist. |
| 401 | key_revoked / key_expired |
The key was revoked or has expired. Make a new one. |
| 403 | insufficient_scope |
The key lacks the scope this endpoint needs; scope names it. |
| 403 | account_inactive |
Your account isn’t active. |
| 403 | api_not_in_plan |
Your plan doesn’t include the API. It comes with the Enterprise and Custom plans. |
| 403 | not_in_sandbox |
A sandbox key (hm_test_…) can’t do this: it would change real data (inviting members). |
| 403 | sandbox_only |
This endpoint takes a sandbox key (hm_test_…) only. |
| 404 | not_found |
No such endpoint, or the thing isn’t yours (or isn’t in the key’s environment). |
| 429 | rate_limited |
More requests in a minute on this key than your plan allows (X-RateLimit-Limit). Wait Retry-After seconds. |
Rate limits
Requests a minute per key follow your plan (120 on Enterprise, set to your volume on Custom); X-RateLimit-Limit says yours, every answer carries X-RateLimit-Remaining, and a 429 carries Retry-After (seconds).