Fehlerbehandlung

Format der Fehlerantwort

Schlägt eine Anfrage fehl, antwortet die API mit einem HTTP-Fehlerstatus und einem JSON-Body mit success: false. Das error-Objekt enthält einen numerischen code, einen maschinenlesbaren type und eine für Menschen lesbare info-Meldung:

{
  "success": false,
  "error": {
    "code": 101,
    "type": "no_api_key",
    "info": "User did not supply an API Key"
  }
}

Verzweigen Sie anhand von code oder type, nicht anhand des info-Texts, der sich ändern kann. Die Codes sind dieselben wie in früheren Versionen von MetalAPI, sodass bestehende Integrationen weiter funktionieren.

Authentifizierungs- und Kontofehler

• 101 no_api_key (401): Die Anfrage enthält keinen API-Schlüssel.
• 102 invalid_api_key (401): Der Schlüssel ist unbekannt oder wurde widerrufen.
• 103 account_inactive (403): Das Konto ist nicht aktiv. Wenden Sie sich an den Support.
• 107 origin_not_allowed (403): Ein domainbeschränkter Schlüssel wurde von einer Website aus verwendet, die nicht auf seiner Liste erlaubter Domains steht.

Limit- und Tariffehler

• 104 too_many_requests (429): Das Limit pro Minute ist erreicht. Warten Sie die im Retry-After-Header angegebene Anzahl von Sekunden.
• 105 quota_exceeded (429): Das Monatskontingent ist bis zum 1. des nächsten Monats (UTC) aufgebraucht.
• 106 plan_restriction (403): Der Endpunkt oder Parameter ist in Ihrem Tarif nicht enthalten, etwa /carat im Free-Tarif oder XAU-BID unterhalb von Standard.

Validierungsfehler

Diese Fehler liefern HTTP-Status 400 und bedeuten, dass die Anfrage selbst korrigiert werden muss:

• 201 invalid_base: unbekanntes base-Symbol.
• 202 invalid_from und 203 invalid_to: unbekanntes from- oder to-Symbol in /convert.
• 204 invalid_amount: amount fehlt oder ist keine Zahl.
• 205 invalid_date: fehlerhaftes Datum oder ein Datum in der Zukunft.
• 206 invalid_timeframe: start_date oder end_date fehlt, oder der Beginn liegt nach dem Ende.
• 207 timeframe_too_long: Der Zeitraum ist länger, als Ihr Tarif erlaubt (30 Tage im Free-Tarif, 365 in kostenpflichtigen Tarifen).
• 208 invalid_symbols: Keines der angefragten Symbole existiert.
• 209 invalid_unit: nicht unterstützte unit.
• 210 invalid_carat: nicht unterstützter Karatwert.

In currencies werden unbekannte Symbole übersprungen, solange mindestens ein Symbol gültig ist.

Weitere Fehler

• 300 no_results (404): Die Abfrage ist gültig, aber es gibt keine Daten, zum Beispiel für ein Datum vor Beginn der Historie eines Symbols.
• 404 invalid_function (404): unbekannter Endpunkt. Prüfen Sie die URL.
• 500 server_error (500): ein unerwarteter Fehler auf unserer Seite.
• 503 service_unavailable (503): Preisdaten sind vorübergehend nicht verfügbar.

Fehler im Code behandeln

Prüfen Sie success bei jeder Antwort und wandeln Sie Fehlschläge in Fehler um, die Ihr Code auswerten kann. Diese Hilfsfunktion kommt auch mit Nicht-JSON-Antworten von Proxys zurecht:

async function metalapi(path, params = {}) {
  const url = new URL(`https://metalapi.com/api/v1/${path}`);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);

  const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
  const data = await res.json().catch(() => ({
    success: false,
    error: { code: res.status, type: "http_error", info: res.statusText },
  }));

  if (!data.success) {
    const err = new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
    err.code = data.error.code;
    err.retryAfter = Number(res.headers.get("Retry-After")) || undefined;
    throw err;
  }
  return data;
}

Strategie für Wiederholungen

Wiederholen Sie nur Fehler, die beim zweiten Versuch erfolgreich sein können:

• 104: Retry-After Sekunden warten, dann erneut versuchen.
• 500, 503 und Netzwerkfehler: mit exponentiellem Backoff (1 s, 2 s, 4 s) wiederholen und nach drei Wiederholungen aufgeben.
• Alles andere (101 bis 103, 105 bis 107, die 2xx-Validierungscodes, 300, 404): nicht wiederholen. Korrigieren Sie stattdessen die Anfrage, den Schlüssel oder den Tarif.

Wiederholungen bei 104- und 5xx-Fehlern kosten nichts, weil diese fehlgeschlagenen Anfragen nicht berechnet werden.

async function withRetry(fn, retries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = err.code === undefined || err.code === 104 || err.code >= 500;
      if (!retryable || attempt >= retries) throw err;
      const delay = err.retryAfter ? err.retryAfter * 1000 : 1000 * 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

const data = await withRetry(() => metalapi("latest", { currencies: "XAU,XAG" }));