Fehler und Rate-Limits

Jeder Endpunkt meldet Fehler im selben Format, mit einem maschinenlesbaren Code und einer Request-ID.

Fehlerantwort

Ein fehlgeschlagener Aufruf liefert success: false. code ist stabil und für Programme gedacht, error ist eine kurze englische Meldung für Menschen, und request_id identifiziert den Aufruf in unseren Logs. param nennt den fehlerhaften Parameter, wenn das Problem in der Eingabe liegt.

Echte Beispiele

Dies sind Live-Antworten, die beim Rendern dieser Seite von der API abgerufen wurden.

Pflichtparameter fehlt · GET /api/sd/oi · HTTP 400

{
  "success": false,
  "error": "coin required",
  "code": "INVALID_PARAM",
  "request_id": "cb-mwefukmp-73c1e99cf4"
}

Unbekannter Endpunkt · HTTP 404

{
  "success": false,
  "code": "NOT_FOUND",
  "error": "unknown endpoint: GET /api/this-endpoint-does-not-exist",
  "request_id": "cb-mwefukmp-94914c8210"
}

Fehlercodes

Code	HTTP	Bedeutung	Empfohlene Reaktion
INVALID_PARAM	400	Ein erforderlicher Parameter fehlt oder ein Wert wird nicht akzeptiert. `param` nennt den Parameter, sofern er bekannt ist.	Nicht unverändert wiederholen; die Anfrage korrigieren.
UNAUTHORIZED	401	Der Header `CB-API-KEY` wurde gesendet, der Schlüssel ist jedoch unbekannt oder widerrufen. Öffentliche Daten erfordern keinen Schlüssel – lassen Sie den Header weg oder verwenden Sie einen gültigen Schlüssel.	Nicht unverändert wiederholen.
FORBIDDEN	403	Die Route gehört nicht zur öffentlichen API (intern oder nur für Konten).	Nicht wiederholen.
NOT_FOUND	404	Unbekannte Route, oder der angefragte Coin / die Börse / der Fonds existiert nicht.	Nicht wiederholen; Pfad und Kennungen mit dem Katalog abgleichen.
RATE_LIMITED	429	Mehr Anfragen, als das Limit pro Minute zulässt. `Retry-After` gibt die Wartezeit in Sekunden an.	`Retry-After` abwarten, dann mit Backoff wiederholen.
INTERNAL	500	Unerwarteter Serverfehler. Die Meldung ist bewusst allgemein gehalten; geben Sie `request_id` an, wenn Sie den Fehler melden.	Einmal nach einigen Sekunden wiederholen; wenn der Fehler bestehen bleibt, mit der Request-ID melden.
UPSTREAM_FAILED	503	Die Datenquelle hinter diesem Endpunkt hat nicht rechtzeitig geantwortet. Es werden ersatzweise keine veralteten oder stellvertretenden Zahlen zurückgegeben.	Mit Backoff wiederholen; die Statusseite prüfen.
UNAVAILABLE	501 / 503	Der Datensatz ist vorübergehend nicht bereit (Cache wird aufgewärmt), oder der Endpunkt hat noch keine rechtmäßige öffentliche Quelle.	Später wiederholen; der Katalog kennzeichnet Endpunkte, die konzeptbedingt nicht verfügbar sind.
REQUEST_FAILED	200	Einige ältere Endpunkte antworten mit HTTP 200 und `success: false`. Prüfen Sie immer `success`, nicht nur den HTTP-Status.	Hängt von der Meldung ab; als fehlgeschlagene Anfrage behandeln.

Ältere Endpunkte können bei einem fehlenden Element mit HTTP 200, success: false und dem Code REQUEST_FAILED antworten. Prüfen Sie success bei jeder Antwort.

Request-ID

Jede Antwort enthält einen X-Request-Id-Header. Fehlerantworten wiederholen ihn im Body als request_id. Antworten aus dem kurzlebigen Edge-Cache tragen die ID der Anfrage, die sie erzeugt hat; identische IDs bei aufeinanderfolgenden Aufrufen bedeuten also, dass Sie eine gecachte Kopie erhalten haben.

Rate-Limits

Die Limits gelten pro Minute: je IP-Adresse bei anonymen Aufrufen und je Schlüssel, wenn ein gültiger CB-API-KEY-Header gesendet wird. Das Limit beträgt 1200 Anfragen pro Minute. Icon-Anfragen unter /api/coin-icon werden nicht mitgezählt.

Rate-Limit-Header

Name	Beschreibung
X-Request-Id	Kennung dieser Anfrage. In Fehlerberichten angeben.
X-RateLimit-Limit	Im aktuellen Ein-Minuten-Fenster erlaubte Anfragen.
X-RateLimit-Remaining	Im aktuellen Fenster verbleibende Anfragen.
X-RateLimit-Reset	Unix-Zeit in Sekunden, zu der das Fenster zurückgesetzt wird.
Retry-After	Wird mit HTTP 429 gesendet: Wartezeit in Sekunden bis zum nächsten Versuch.
X-Cache	HIT, STALE oder MISS für den serverseitigen Antwort-Cache.

Bei Überschreitung des Limits

Die API antwortet mit HTTP 429 und dem Code RATE_LIMITED. Warten Sie die in Retry-After angegebene Anzahl Sekunden ab und wiederholen Sie dann die Anfrage. Wer schneller abfragt, als die Cache-TTL eines Endpunkts abläuft, erhält dieselbe gecachte Antwort; richten Sie Ihr Abfrageintervall daher an der TTL aus, die auf der jeweiligen Referenzseite steht.

Wiederholung mit Backoff

JavaScript

async function getJson(url, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url);
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get("Retry-After")) || 2 ** i;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const body = await res.json();
    if (body.success === false) {
      throw new Error(body.code + ": " + body.error + " (" + body.request_id + ")");
    }
    return body;
  }
  throw new Error("gave up after " + tries + " attempts");
}

Keine Daten sind kein Fehler

Sind die Parameter gültig, es gibt aber keine rechtmäßige öffentliche Quelle für die Daten, ist der Aufruf mit HTTP 200 erfolgreich: Die Wertfelder sind null, meta.quality ist UNAVAILABLE, und coverage.unavailable nennt den Grund. Stellen Sie den Wert als Strich dar. Wandeln Sie ihn nicht in 0 um.

Veraltete Daten

Gerät ein Collector in Rückstand, liefern die Endpunkte weiterhin die zuletzt gespeicherten Werte mit meta.is_stale: true, bis diese das Nutzbarkeitsfenster überschreiten; danach werden sie aus den Aggregaten entfernt und in coverage.stale_excluded aufgeführt.