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