# Scopes und Fehler

> Die Scopes, die ein Schlüssel haben kann, die Fehler, die jeder Endpunkt zurückgeben kann, und das 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

Jeder Schlüssel hat eigene Scopes, die beim Erstellen festgelegt werden.

| Scope | Was er erlaubt |
| --- | --- |
| `members:read` | Ihre Artists und Labels auflisten. |
| `members:write` | Neue Artists und Labels unter Ihr Konto einladen. |
| `catalog:read` | Releases, Tracks und ihre Auslieferung an die Stores. |
| `earnings:read` | Erlöse nach Monat, Release oder Store. |
| `payouts:read` | Ihr Guthaben und Ihre Auszahlungsanfragen. |
| `links:read` | Smart Links und Pre-Saves mit ihren Statistiken. |
| `ddex:write` | DDEX-ERN-Batches liefern (ZIP; empfohlen 4.3, akzeptiert 4.2/4.1/3.8.x/3.7), die zu Release-Entwürfen werden, und ihren Status lesen. |
| `ddex:validate` | ERN-Nachrichten und -Batches (jede akzeptierte Version) mit allen Prüfungen einer Auslieferung testen; es wird nichts angelegt. |
| `webhooks:read` | Ihre Webhook-Endpunkte auflisten und was an sie gesendet wurde. |
| `webhooks:write` | Webhook-Endpunkte anlegen, ändern und löschen, ihre Secrets erneuern, Test-Events senden und Zustellungen wiederholen. |

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

## Fehler

Fehler antworten mit `{ "error": "…", "code": "…" }` (dazu `field` bei ungültiger Eingabe und `scope` bei einem fehlenden Scope).

| Status | Code | Bedeutung |
| --- | --- | --- |
| 400 | `invalid` | Ein Parameter ist fehlerhaft; field nennt ihn. |
| 401 | `unauthenticated` | Kein Header Authorization: Bearer. |
| 401 | `invalid_key` | Der Schlüssel existiert nicht. |
| 401 | `key_revoked / key_expired` | Der Schlüssel wurde widerrufen oder ist abgelaufen. Erstellen Sie einen neuen. |
| 401 | `test_keys_retired` | Ein Testschlüssel (hm_test_…), eingestellt am 12. Oktober 2026. Verwenden Sie einen Produktionsschlüssel (hm_live_…) und testen Sie mit POST /ddex/validate. |
| 403 | `insufficient_scope` | Dem Schlüssel fehlt der Scope, den dieser Endpunkt braucht; scope nennt ihn. |
| 403 | `account_inactive` | Ihr Konto ist nicht aktiv. |
| 403 | `api_not_in_plan` | Ihr Tarif enthält die API nicht. Sie ist Teil der Tarife Enterprise und Custom. |
| 404 | `not_found` | Diesen Endpunkt gibt es nicht, oder das Objekt gehört nicht Ihnen. |
| 429 | `rate_limited` | Mehr Anfragen pro Minute mit diesem Schlüssel, als Ihr Tarif erlaubt (X-RateLimit-Limit). Warten Sie Retry-After Sekunden. |

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

## Rate Limits

Die Anfragen pro Minute und Schlüssel richten sich nach Ihrem Tarif (120 bei Enterprise, bei Custom auf Ihr Volumen abgestimmt); `X-RateLimit-Limit` nennt Ihr Limit, jede Antwort enthält `X-RateLimit-Remaining`, und eine 429-Antwort enthält `Retry-After` (in Sekunden).

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