Fehler

Alle API-Key-Endpunkte geben JSON zurück. Bei jeder Antwort, die nicht zum Statuscode 2xx gehört, hat der Antworttext denselben Aufbau:

{
  "success": false,
  "error": "<human-readable message>"
}

Manche Fehler enthalten zusätzlichen Kontext (z. B. Im Abspann (bei einem 429-Quotenfehler). Der HTTP-Statuscode ist die maßgebliche Quelle – je nach Status verzweigen, dann lesen Fehler zur Anzeige oder Protokollierung.

Statuscode-Übersicht#

Die beiden unterscheiden 429 Fälle#

A 429 bedeutet immer „vorerst nicht mehr senden“, aber warum ist wichtig.

Ratenbegrenzung (60 pro Minute und Benutzer):

{
  "success": false,
  "error": "Rate limit exceeded. Max 60 requests per minute."
}

Monatliches Guthabenlimit (20.000 pro Monat und Nutzer):

{
  "success": false,
  "error": "Monthly credit limit reached (20000). Resets next month.",
  "credits": { "used": 20000, "limit": 20000, "remaining": 0 }
}

Verzweigung je nach Vorhandensein des Im Abspann Objekt oder bei einer Übereinstimmung mit einer Teilzeichenfolge für „Monatliches Kreditlimit“. Siehe Ratenbegrenzungen und Impressum & Rechnungsstellung für die jeweilige Wiederherstellungsstrategie.

Muster zur Fehlerbehandlung (Node.js)#

async function whFetch(path, init = {}) {
  const res = await fetch(`${ORIGIN}${path}`, {
    ...init,
    headers: { 'X-API-Key': process.env.WH_API_KEY, ...(init.headers || {}) },
  });

  let body = null;
  try { body = await res.json(); } catch { /* non-JSON, leave null */ }

  if (res.ok) return body;

  const error = (body && body.error) || res.statusText;

  if (res.status === 401) throw new Error(`Auth failed: ${error}`);
  if (res.status === 403) throw new Error(`Plan required: ${error}`);
  if (res.status === 404) throw new Error(`Unknown endpoint: ${path}`);
  if (res.status === 429) {
    const retryable = body && body.credits ? false : true; // monthly quota is not retryable today
    const err = new Error(error);
    err.retryable = retryable;
    throw err;
  }
  if (res.status >= 500) {
    const err = new Error(`Upstream error: ${error}`);
    err.retryable = true;
    throw err;
  }
  throw new Error(`HTTP ${res.status}: ${error}`);
}

Muster zur Fehlerbehandlung (Python)#

import os, requests

def wh_fetch(path, **kwargs):
    r = requests.request(
        method=kwargs.pop("method", "GET"),
        url=f"{ORIGIN}{path}",
        headers={"X-API-Key": os.environ["WH_API_KEY"], **kwargs.pop("headers", {})},
        **kwargs,
    )

    body = None
    try:
        body = r.json()
    except ValueError:
        pass

    if r.ok:
        return body

    error = (body or {}).get("error") or r.reason

    if r.status_code == 401:
        raise PermissionError(f"Auth failed: {error}")
    if r.status_code == 403:
        raise PermissionError(f"Plan required: {error}")
    if r.status_code == 429:
        is_quota = bool((body or {}).get("credits"))
        raise RuntimeError(f"Rate limited (quota={is_quota}): {error}")
    if r.status_code >= 500:
        raise RuntimeError(f"Upstream error: {error}")

    raise RuntimeError(f"HTTP {r.status_code}: {error}")

Antwortformat vs. HTTP-Status#

• Fehler beim Schutz des API-Schlüssels mit Datenvolumenbegrenzung (401, 403, Grenze 429, allgemeiner Begriff 500) geben immer JSON zurück mit Erfolg: false und einen entsprechenden HTTP-Status.
• Einige JSON-Handler (insbesondere große TikTok-Shop-Payloads) können HTTP-Antworten zurückgeben 200 bei einem Body, der Flags auf Unternehmensebene enthält – lesen Sie immer das Schema für diesen Endpunkt, anstatt davon auszugehen, dass Erfolg erfasst ausschließlich HTTP-Daten.

HTML statt JSON? Festgelegte programmatische Routen mit Messung Content-Type: application/json. HTML deutet in der Regel auf einen falschen Host, eine Proxy-Fehlerseite oder einen Pfad hin, der nie von der App aufgerufen wurde – siehe Fehlerbehebung.

Fehler melden#

Wenn du auf eine 500 oder eine Antwort, die im Widerspruch zur Dokumentation steht:

1. Erfassen Sie die URL der Anfrage, die Methode, die Header (bitte schwärzen Sie Ihren Schlüssel) und den Textkörper.
2. Erfassen Sie den Antwortstatus und den Antworttext.
3. Beachten Sie den Zeitstempel.
4. Senden Sie das Datenpaket an den Support – das Team kann es anhand der Benutzer-ID und des Zeitstempels mit den Serverprotokollen abgleichen.