# Scopes and errors

> The scopes a key can have, the errors every endpoint can answer, and the 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. -->

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

Source: https://developer.hillsmusic.com/reference/scopes-and-errors/