Fehler

Schlägt eine Anfrage fehl, antwortet die API mit einem 4xx- oder 5xx-Status und einem JSON-Body mit einem stabilen code. Verzweigen Sie anhand von code. Der Text in error ist für Menschen gedacht und kann sich ändern.

Das Format

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

Einige Fehler enthalten eigene Felder. So listet 409 upload_incomplete die Teile in missing und wrong_size auf.

Fehler, die jeder Endpunkt zurückgeben kann

404 not_found steht sowohl für „existiert nicht“ als auch für „gehört einem anderen Konto“. Die API verrät nie, dass ein Release eines anderen Kontos existiert.

Fehler einzelner Endpunkte

Jede Referenzseite listet die Fehler ihrer Endpunkte auf. Die gemeinsamen stehen unter Scopes und Fehler.

Validierungsfehler

Ein 400 invalid nennt das erste gefundene Problem:

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

Es wird immer nur ein Feld gemeldet. Korrigieren Sie es und senden Sie die Anfrage erneut. Wenn Sie ein Formular auf der API aufbauen, zeigen Sie error neben dem Eingabefeld an, das field nennt.

Bei DDEX-Dateien ist das anders. Ein DDEX-Batch mit Problemen ergibt kein 400. Der Test antwortet mit 200, allen Prüfungen und einem Ergebnis, und eine Auslieferung antwortet mit 202 und meldet Probleme pro Release. Siehe DDEX-Auslieferung.

Was Sie wiederholen sollten

• Wiederholen Sie 429 und 5xx sowie Netzwerkfehler wie Timeouts und abgebrochene Verbindungen.
• Nicht wiederholen sollten Sie andere 4xx. Dieselbe Anfrage erhält dieselbe Antwort. Korrigieren Sie zuerst die Anfrage, den Schlüssel oder seine Scopes.

Warten Sie bei 429 so viele Sekunden, wie Retry-After angibt. Warten Sie bei 5xx nach jedem Versuch länger (1 s, 2 s, 4 s …) und geben Sie nach einigen Versuchen auf. Siehe Rate Limits.

Lesezugriffe können Sie gefahrlos wiederholen. Bei Schreibzugriffen sollten Sie vorher nachdenken: Ein wiederholtes POST /ddex nach einer verlorenen Antwort kann den Batch zweimal einreihen. Prüfen Sie zuerst mit GET /ddex, ob er schon da ist.

Ein Node-Fehlerhandler

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;
}

Mit curl sehen Sie den Status mit -w '%{http_code}', die Header mit -i:

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