Scopes et erreurs
Les scopes qu’une clé peut avoir, les erreurs que chaque endpoint peut renvoyer et la limite de débit.
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. |
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. |
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).