Erreurs

Quand une requête échoue, l’API renvoie un statut 4xx ou 5xx et un corps JSON avec un code stable. Basez votre logique sur code. Le texte de error s’adresse à des personnes et peut changer.

Le format

{
  "error": "This API key doesn't have the earnings:read scope.",
  "code": "insufficient_scope",
  "scope": "earnings:read"
}

Quelques erreurs ajoutent leurs propres champs. Par exemple, 409 upload_incomplete liste les parties missing et wrong_size.

Erreurs possibles sur tous les endpoints

404 not_found couvre à la fois « n’existe pas » et « appartient à un autre compte ». L’API ne vous révèle jamais l’existence de la sortie de quelqu’un d’autre.

Erreurs propres à certains endpoints

Chaque page de la référence liste les erreurs de chaque endpoint. Scopes et erreurs regroupe les erreurs communes.

Erreurs de validation

Une 400 invalid désigne le premier problème rencontré :

{
  "error": "updated_since is an ISO date or time.",
  "code": "invalid",
  "field": "updated_since"
}

Un seul champ est signalé à la fois. Corrigez-le et renvoyez la requête. Si vous construisez un formulaire au-dessus de l’API, affichez error à côté du champ désigné par field.

Les fichiers DDEX fonctionnent autrement. Un lot DDEX qui pose problème ne renvoie pas de 400. Le test renvoie 200 avec toutes les vérifications et un verdict, et une livraison renvoie 202 puis signale les problèmes sortie par sortie. Voir Livraison DDEX.

Quoi retenter

• Retentez les 429 et les 5xx, ainsi que les erreurs réseau comme les délais dépassés et les connexions réinitialisées.
• Ne retentez pas les autres 4xx. La même requête obtiendra la même réponse. Corrigez d’abord la requête, la clé ou ses scopes.

Pour une 429, attendez le nombre de secondes indiqué dans Retry-After. Pour une 5xx, attendez plus longtemps après chaque essai (1 s, 2 s, 4 s…) et abandonnez au bout de quelques tentatives. Voir Limites de débit.

Les lectures peuvent être retentées sans risque. Réfléchissez avant de retenter une écriture : un POST /ddex relancé après une réponse perdue peut mettre le lot deux fois en file d’attente. Vérifiez d’abord sa présence avec GET /ddex.

Un gestionnaire d’erreurs Node

export class HillsError extends Error {
  constructor(status, body, headers) {
    super(body.error ?? `HTTP ${status}`);
    this.status = status;
    this.code = body.code;
    this.field = body.field;
    this.scope = body.scope;
    this.retryAfter = Number(headers.get("Retry-After")) || null;
  }
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function hills(path, init = {}, tries = 4) {
  for (let i = 1; ; i++) {
    const res = await fetch("https://api.hillsmusic.com/v1" + path, {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
    });
    const body = await res.json().catch(() => ({}));
    if (res.ok) return body;
    const err = new HillsError(res.status, body, res.headers);
    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || i >= tries) throw err;
    await sleep(err.retryAfter ? err.retryAfter * 1000 : 1000 * 2 ** (i - 1));
  }
}

try {
  await hills("/earnings");
} catch (err) {
  if (err.code === "insufficient_scope") console.error(`Add ${err.scope} to this key.`);
  else if (err.code === "api_not_in_plan") console.error("The plan doesn't include the API.");
  else throw err;
}

Avec curl, ajoutez -w '%{http_code}' pour voir le statut, ou -i pour voir les en-têtes :

curl -i "https://api.hillsmusic.com/v1/releases/999999" \
  -H "Authorization: Bearer $HILLS_API_KEY"
# HTTP/2 404
# {"error":"…","code":"not_found"}