# Scopes et erreurs

> Les scopes qu’une clé peut avoir, les erreurs que chaque endpoint peut renvoyer et la limite de débit.

<!-- Generated from openapi/hills-v1.json by scripts/api-reference.mjs. Edit the operation in hills-music (server/lib/ops), not this page. -->

## Scopes

Chaque clé a ses propres scopes, choisis à sa création.

| Scope | Ce qu’il autorise |
| --- | --- |
| `members:read` | Lister vos artistes et labels. |
| `members:write` | Inviter de nouveaux artistes et labels sous votre compte. |
| `catalog:read` | Sorties, titres et leur livraison aux plateformes. |
| `earnings:read` | Revenus par mois, par sortie ou par plateforme. |
| `payouts:read` | Votre solde et vos demandes de retrait. |
| `links:read` | Smart links et pré-sauvegardes avec leurs statistiques. |
| `ddex:write` | Livrer des lots DDEX ERN (zip ; 4.3 recommandée, 4.2/4.1/3.8.x/3.7 acceptées) qui deviennent des sorties en brouillon, et consulter leur statut. |
| `ddex:validate` | Tester des messages et des lots ERN (toute version acceptée) avec toutes les vérifications d’une livraison ; rien n’est créé. |
| `webhooks:read` | Lister vos endpoints webhook et ce qui leur a été envoyé. |
| `webhooks:write` | Créer, modifier et supprimer des endpoints webhook, renouveler leurs secrets, envoyer des événements de test et relancer des livraisons. |

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

## Erreurs

Les erreurs renvoient `{ "error": "…", "code": "…" }` (plus `field` pour une entrée invalide et `scope` pour un scope manquant).

| Statut | Code | Signification |
| --- | --- | --- |
| 400 | `invalid` | Un paramètre est incorrect ; field l’indique. |
| 401 | `unauthenticated` | Aucun en-tête Authorization: Bearer. |
| 401 | `invalid_key` | La clé n’existe pas. |
| 401 | `key_revoked / key_expired` | La clé a été révoquée ou a expiré. Créez-en une nouvelle. |
| 401 | `test_keys_retired` | Une clé de test (hm_test_…), retirée le 12 octobre 2026. Utilisez une clé de production (hm_live_…) et testez avec POST /ddex/validate. |
| 403 | `insufficient_scope` | La clé n’a pas le scope requis par cet endpoint ; scope l’indique. |
| 403 | `account_inactive` | Votre compte n’est pas actif. |
| 403 | `api_not_in_plan` | Votre offre n’inclut pas l’API. Elle est fournie avec les offres Enterprise et Custom. |
| 404 | `not_found` | Endpoint inexistant, ou ressource qui ne vous appartient pas. |
| 429 | `rate_limited` | Plus de requêtes en une minute sur cette clé que votre offre n’en autorise (X-RateLimit-Limit). Attendez le nombre de secondes indiqué par Retry-After. |

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

## Limites de débit

Le nombre de requêtes par minute et par clé dépend de votre offre (120 sur Enterprise, ajusté à votre volume sur Custom) ; `X-RateLimit-Limit` indique le vôtre, chaque réponse porte `X-RateLimit-Remaining`, et une 429 porte `Retry-After` (en secondes).

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