Fehlerbehandlung

Die Trade Hub API verwendet standardmäßige HTTP-Statuscodes, um den Erfolg oder das Scheitern einer Anfrage anzuzeigen. Codes im Bereich 2xx zeigen Erfolg an, 4xx-Codes weisen auf einen Clientfehler hin und 5xx-Codes auf einen Serverfehler.

Fehlerantwortformat

Alle Fehler geben einen JSON-Body mit einem detail-Feld zurück, das das Problem beschreibt:

{
  "detail": "Fehlerbeschreibung"
}

Bei Validierungsfehlern (422) enthält das Format zusätzliche Details:

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Feld erforderlich",
      "type": "missing"
    }
  ]
}

Fehlercodes

401 Unauthorized

Ungültiger oder fehlender API-Schlüssel. Überprüfen Sie, ob der Header X-API-Key vorhanden ist und einen gültigen Schlüssel enthält.

{
  "detail": "Ungültiger oder fehlender API-Schlüssel"
}

Häufige Ursachen:

• Header X-API-Key fehlt in der Anfrage
• API-Schlüssel abgelaufen oder widerrufen
• Schlüssel mit zusätzlichen Leerzeichen oder Zeichen kopiert
• API-Schlüssel von einem Organisationsadministrator deaktiviert

Lösung:

• Überprüfen Sie die korrekte Schreibweise des Headers (X-API-Key, nicht X-Api-Key)
• Prüfen Sie, ob der Schlüssel im Developer Dashboard aktiv ist
• Schlüssel bei Bedarf neu generieren

402 Payment Required

Unzureichendes Guthaben oder Ausgabenlimit erreicht. Ihre Organisation hat keine Guthaben mehr oder das monatliche Ausgabenlimit wurde erreicht.

{
  "detail": "unzureichendes Guthaben"
}

Häufige Ursachen:

• Aufgeladenes Guthaben erschöpft (Guthabenmodus)
• Monatliches Ausgabenlimit erreicht (Rechnungsmodus)

Zusätzliche Header:

• X-Balance-Cents: aktuelles Guthaben in Cent (Guthabenmodus)
• X-Spending-Limit / X-Spending-Current: Limit und aktuelle Ausgaben (Rechnungsmodus)

Lösung:

• Laden Sie Ihr Guthaben im Billing Dashboard auf
• Passen Sie Ihr Ausgabenlimit bei Bedarf an
• Aktivieren Sie die automatische Aufladung, um Unterbrechungen zu vermeiden

403 Forbidden

Unzureichende Berechtigungen. Ihr API-Schlüssel verfügt nicht über die erforderlichen Rechte für diese Operation.

{
  "detail": "Unzureichende Berechtigungen für diese Operation"
}

Häufige Ursachen:

• Versuch, auf eine Ressource einer anderen Organisation zuzugreifen
• API-Schlüssel mit eingeschränkten Berechtigungen
• API-Schlüsselumfang nicht ausreichend für diese Ressource

Lösung:

• Überprüfen Sie, ob die Ressource zu Ihrer Organisation gehört
• Kontaktieren Sie Ihren Organisationsadministrator, um die Berechtigungen anzupassen

404 Not Found

Ressource nicht gefunden. Die angegebene Kennung entspricht keiner vorhandenen Ressource.

{
  "detail": "Job nicht gefunden"
}

Häufige Ursachen:

• Falsche Job- oder Batch-Kennung
• Ressource gelöscht
• Kennung einer anderen Organisation

Lösung:

• Prüfen Sie die Kennung in Ihrer Anfrage
• Verwenden Sie den History-Endpunkt, um die korrekte Ressource zu finden

422 Unprocessable Entity

Validierungsfehler. Der Anfrage-Body entspricht nicht dem erwarteten Format.

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Feld erforderlich",
      "type": "missing"
    }
  ]
}

Häufige Ursachen:

• Erforderliches Feld fehlt (content)
• Falscher Datentyp (String statt Array)
• Wert außerhalb der akzeptierten Grenzen
• Ungültiges JSON-Format im Anfrage-Body

Lösung:

• Prüfen Sie die Endpunktdokumentation auf erforderliche Parameter
• Validieren Sie Ihr JSON vor dem Senden
• Überprüfen Sie die Datentypen für jedes Feld

429 Too Many Requests

Rate Limit überschritten. Sie haben zu viele Anfragen innerhalb des Zeitfensters gesendet.

{
  "detail": "Rate limit überschritten. Wiederholen Sie die Anfrage in 12 Sekunden."
}

Lösung:

• Warten Sie die im Retry-After-Header angegebene Zeit ab
• Implementieren Sie exponentielles Backoff
• Verwenden Sie Batch-Klassifizierung, um die Anzahl der Anfragen zu reduzieren

500 Internal Server Error

Interner Serverfehler. Auf der Serverseite ist ein unerwarteter Fehler aufgetreten.

{
  "detail": "Interner Serverfehler"
}

Lösung:

• Wiederholen Sie die Anfrage nach einigen Sekunden
• Falls der Fehler weiterhin besteht, kontaktieren Sie den Support mit der Anfragenkennung
• Prüfen Sie die Statusseite auf laufende Vorfälle

503 Service Unavailable

Dienst vorübergehend nicht verfügbar. Der Dienst befindet sich in Wartung oder ist überlastet.

{
  "detail": "Dienst vorübergehend nicht verfügbar. Bitte versuchen Sie es später erneut."
}

Lösung:

• Versuchen Sie es nach einigen Minuten erneut
• Prüfen Sie die Statusseite auf geplante Wartungen
• Implementieren Sie eine Warteschlangenmechanik für fehlgeschlagene Anfragen

Zusammenfassungstabelle

Empfohlene Handhabung

import httpx

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_your_api_key"},
)

response = client.post("/v1/classify/jobs", json={
    "content": "Wireless Bluetooth headphones"
})

match response.status_code:
    case 201:
        job = response.json()
        print(f"Job erstellt: {job['id']}")
    case 401:
        print("Authentifizierungsfehler. Überprüfen Sie Ihren API-Schlüssel.")
    case 402:
        print("Unzureichendes Guthaben. Laden Sie Ihre Credits auf.")
    case 422:
        errors = response.json()["detail"]
        for error in errors:
            print(f"Validierung: {error['loc']} - {error['msg']}")
    case 429:
        retry_after = int(response.headers.get("Retry-After", 10))
        print(f"Rate Limit erreicht. Wiederholen in {retry_after}s.")
    case code if code >= 500:
        print(f"Serverfehler ({code}). Später erneut versuchen.")
    case _:
        print(f"Unerwarteter Fehler: {response.status_code}")