Fehlerbehandlung

Verstehen Sie die Fehlerantworten der ChartQuery API und lernen Sie, jeden Fall korrekt zu behandeln.

Jede Anfrage an die ChartQuery API gibt einen Standard-HTTP-Statuscode zurück. Diese Anleitung erklärt, was jeder Code bedeutet, wann Credits verbraucht werden und wie Fehler in Ihrer Integration behandelt werden.

Antwortformat

Erfolgreiche Antworten geben ein JSON-Objekt mit den Daten des Endpunkts zurück. Fehlerantworten folgen einer einheitlichen Struktur:

{
  "error": "Human-readable description of what went wrong"
}

Prüfen Sie den HTTP-Statuscode immer, bevor Sie den Body lesen.

Statuscodes

`200` Erfolgreich

Abgerechnet. Die Anfrage wurde erfolgreich abgeschlossen. Credits werden von Ihrem Guthaben abgezogen.

const res = await fetch(url, { headers: { "x-api-key": API_KEY } })

if (res.status === 200) {
  const data = await res.json()
  // process data
}

`201` Job erstellt

Abgerechnet. Ein asynchroner Job wurde erstellt und akzeptiert. Credits werden sofort beim Einreihen in die Warteschlange abgezogen.

`202` Akzeptiert (async)

Noch nicht abgerechnet. Die Anfrage wurde akzeptiert und in die Warteschlange eingereiht. Verwenden Sie die zurückgegebene Job-ID, um das Ergebnis abzufragen. Credits werden erst abgerechnet, wenn der Job erfolgreich abgeschlossen wurde.

`400` Ungültige Anfrage

Nicht abgerechnet. Ihre Anfrage enthält ungültige oder fehlende Parameter.

Häufige Ursachen:

Ein erforderlicher Query-Parameter fehlt
Ein Parameterwert hat den falschen Typ oder das falsche Format
Der Anfrage-Body ist fehlerhaft

Was tun: Lesen Sie die Endpunkt-Dokumentation erneut durch und überprüfen Sie jeden erforderlichen Parameter. Protokollieren Sie die vollständige Anfrage-URL, um Tippfehler zu erkennen.

if (res.status === 400) {
  const { error } = await res.json()
  console.error("Bad request:", error)
  // do not retry, fix the parameters first
}

`401` Nicht autorisiert

Nicht abgerechnet. Wird bei Authentifizierungsproblemen und Ratenbegrenzungen zurückgegeben. Prüfen Sie die Fehlermeldung, um sie zu unterscheiden.

Ihr x-api-key-Header fehlt oder enthält einen nicht erkannten Wert.

Behebung: Kopieren Sie Ihren Schlüssel aus Ihrem Dashboard → API-Schlüssel und stellen Sie sicher, dass der x-api-key-Header bei jeder Anfrage vorhanden ist.

Der Schlüssel existiert, wurde aber deaktiviert.

Behebung: Gehen Sie zu Ihrem Dashboard → API-Schlüssel und aktivieren Sie den Schlüssel oder generieren Sie einen neuen.

Der Schlüssel hat sein Ablaufdatum überschritten.

Behebung: Generieren Sie einen neuen Schlüssel oder verlängern Sie das Ablaufdatum über Ihr Dashboard.

Sie haben in kurzer Zeit zu viele Anfragen gesendet.

Behebung: Warten Sie und wiederholen Sie dann. Wenn dies regelmäßig vorkommt, erwägen Sie ein Upgrade Ihres Plans.

if (res.status === 401) {
  const { error } = await res.json()
  if (error.toLowerCase().includes("rate limit")) {
    await new Promise(r => setTimeout(r, 2000))
    // retry
  }
}

`402` Zahlung erforderlich

Nicht abgerechnet. Ihr Kreditguthaben ist leer. Die Anfrage wurde nicht ausgeführt.

Was tun:

Laden Sie Ihr Guthaben über Ihr Dashboard auf.
Oder aktivieren Sie die Automatische Aufladung, um dies künftig zu verhindern.

Die automatische Aufladung wird nur ausgelöst, wenn Ihr Guthaben unter den konfigurierten Schwellenwert fällt. Sie läuft nie nach einem festen Zeitplan oder zu einer bestimmten Uhrzeit. Eine integrierte 72-Stunden-Abklingzeit verhindert außerdem mehrere Abbuchungen in kurzer Zeit: Sobald eine Aufladung erfolgt ist, kann sie unabhängig von Ihrer Guthabenbewegung 72 Stunden lang nicht erneut ausgelöst werden. Bei einem fehlgeschlagenen Abbuchungsversuch wird die automatische Aufladung automatisch deaktiviert, um Ihr Konto zu schützen.

Wiederholen Sie eine 402-Antwort nicht sofort. Der Aufruf wird weiterhin fehlschlagen, bis Sie Credits hinzufügen. Richten Sie eine Benachrichtigung ein, damit Ihr Team informiert wird.

if (res.status === 402) {
  // alert your team or trigger an auto top-up flow
  throw new Error("Insufficient credits. Top up at https://app.chartquery.com")
}

`403` Verboten

Nicht abgerechnet. Ihr Schlüssel hat keine Berechtigung, auf diesen Endpunkt zuzugreifen.

Was tun: Überprüfen Sie, ob die Berechtigungen Ihres Schlüssels den aufgerufenen Endpunkt abdecken. Kontaktieren Sie den Support, wenn Sie der Meinung sind, dass dies ein Fehler ist.

`404` Nicht gefunden

Kann abgerechnet werden (endpunktspezifisch). Die Ressource wurde nicht gefunden. Prüfen Sie die Dokumentation des jeweiligen Endpunkts, ob diese Antwort berechnet wird.

if (res.status === 404) {
  // handle "no result" gracefully, not as a fatal error
  return null
}

`500` Interner Serverfehler

Nicht abgerechnet. Auf unserer Seite ist ein unerwarteter Fehler aufgetreten.

Was tun: Wiederholen Sie mit exponentiellem Backoff. Wenn das Problem anhält, wenden Sie sich an den Support.

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options)

    if (res.status !== 500 || attempt === maxRetries) return res

    const delay = 500 * 2 ** attempt
    console.warn(`500 error, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`)
    await new Promise(r => setTimeout(r, delay))
  }
}

Vollständiger Fehler-Handler

Eine einzelne Funktion, die jeden Statuscode abdeckt:

interface ApiResult<T> {
  data: T | null
  error: string | null
  status: number
  billed: boolean
}

async function apiCall<T>(url: string, apiKey: string): Promise<ApiResult<T>> {
  const res = await fetch(url, {
    headers: { "x-api-key": apiKey },
  })

  // 200 and 201 are always billed; 404 billing is endpoint-specific
  const billed = res.status === 200 || res.status === 201

  if (res.status === 200) {
    return { data: await res.json() as T, error: null, status: 200, billed }
  }

  const body = await res.json().catch(() => ({ error: "Unknown error" }))
  const error = body?.error ?? "Unknown error"

  switch (res.status) {
    case 400:
      console.error("[400] Bad request, fix your parameters:", error)
      break
    case 401:
      if (error.toLowerCase().includes("rate limit")) {
        console.warn("[401] Rate limit, back off and retry")
      } else {
        console.error("[401] Auth error, check your API key:", error)
      }
      break
    case 402:
      console.error("[402] No credits remaining. Top up at https://app.chartquery.com")
      break
    case 403:
      console.error("[403] Forbidden, check your key permissions")
      break
    case 404:
      console.warn("[404] Not found, no result for this request")
      break
    case 500:
      console.error("[500] Server error, retry with backoff")
      break
    default:
      console.error(`[${res.status}] Unexpected status:`, error)
  }

  return { data: null, error, status: res.status, billed }
}

Wiederholungsstrategie

Status	Wiederholen?	Strategie
`400`	Nein	Anfrage zuerst korrigieren
`401` (Ratenlimit)	Ja	2–5 s warten, dann wiederholen
`401` (Auth)	Nein	API-Schlüssel korrigieren
`402`	Nein	Zuerst Credits aufladen
`403`	Nein	Berechtigungen prüfen
`404`	Nein	Als leeres Ergebnis behandeln
`500`	Ja	Exponentielles Backoff (max. 3 Versuche)

Abrechnungsübersicht

Status	Abgerechnet
`200`	Ja
`201`	Ja
`404`	Endpunktspezifisch (siehe Endpunkt-Dokumentation)
Alle anderen Codes	Nein

Besuchen Sie die Credits-Seite für eine vollständige Kostenübersicht pro Endpunkt. Weitere Integrationstipps finden Sie unter Best Practices.

Auf dieser Seite