Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Fehlerbehandlung

Gilt für

Produkt: Cloud · Server · Zielgruppe: Entwickler / Integrator

Die Fehler, die die API zurückgibt – ungültiger Schlüssel, unbekanntes Modell, Kontext zu groß, Zeitüberschreitung –, was sie bedeuten und wie ein Client richtig darauf reagiert. Seit basebox 1.8 sind die Fehlermeldungen präzise: Ein ungültiger Schlüssel liefert einen Authentifizierungsfehler, ein unbekanntes Modell, ein Timeout oder eine zu große Anfrage jeweils eine klare, spezifische Meldung.

Die Fehler im Überblick

HTTP-Status	Bedeutung	Typische Ursache	Client-Verhalten
400 Bad Request	Anfrage fehlerhaft	Ungültiges JSON, model oder messages fehlen, ungültige Rolle (human statt user)	Nicht wiederholen; Anfrage korrigieren
401 Unauthorized	Authentifizierung fehlgeschlagen	„Bearer " fehlt, Schlüssel falsch oder gelöscht, REST-API auf dem Server nicht aktiviert	Nicht wiederholen; Schlüssel und Header prüfen, ggf. neuen Schlüssel beim Administrator anfordern
403 Forbidden	Keine Berechtigung	Lizenz deckt die API nicht ab, falscher X-Realm, Organisation nicht berechtigt	Nicht wiederholen; Realm prüfen, Administrator kontaktieren
404 Not Found	Endpunkt oder Modell unbekannt	Falscher Pfad (/api/v1/… statt /v1/…), Modellbezeichner falsch geschrieben	Nicht wiederholen; Pfad prüfen, /v1/models abfragen
Kontext zu groß	Die Anfrage überschreitet, was das Modell fassen kann	Zu lange Nachrichtenhistorie, große eingebettete Dokumente	Eingabe kürzen: Historie zusammenfassen, Dokumente aufteilen
Zeitüberschreitung	Die Anfrage dauerte zu lange	Sehr lange Antwort, hoher Reasoning-Aufwand, überlastete Inferenz	Mit Backoff wiederholen; Streaming nutzen; Ausgabelimit setzen
500 / 502 / 503	Serverfehler	Inferenz-Endpunkt nicht erreichbar, interner Fehler	Mit exponentiellem Backoff wiederholen (begrenzt); dann Support

Die genauen Meldungstexte für „Modell unbekannt", „Anfrage zu groß" und „Zeitüberschreitung" sind so formuliert, dass sie sich Nutzern anzeigen lassen.

Das Fehlerformat

Fehler kommen als JSON-Body im OpenAI-kompatiblen Schema mit einem error-Objekt (Meldung, Typ, ggf. Code). Lesen Sie den Body immer aus – auch bei Statuscodes, die Sie kennen; die Meldung nennt den konkreten Grund.

Wiederholen – aber richtig

Wiederholen: Zeitüberschreitungen, 5xx-Fehler, abgebrochene Streams. Exponentieller Backoff (z. B. 1 s, 2 s, 4 s, 8 s), maximal 3–5 Versuche, mit Zufallsanteil (Jitter), damit viele Clients nicht gleichzeitig wiederholen.

Nicht wiederholen: 400, 401, 403, 404, Kontext zu groß. Die Anfrage wird beim zweiten Mal genauso scheitern. Beheben Sie die Ursache.

Idempotenz: Eine Chat-Completion hat keine Nebenwirkungen; wiederholen ist gefahrlos. Bei Tool Calling, das in Ihren Systemen etwas verändert, prüfen Sie vor der Wiederholung, ob die Aktion bereits ausgeführt wurde.

Kontext zu groß vermeiden

Jedes Modell hat eine Kontextgröße (siehe „Über" in der Oberfläche). Ihre Anfrage – Systemnachricht, gesamte Historie, Anhänge und die erwartete Antwort – muss hineinpassen.

• Halten Sie die Historie kurz: ältere Runden zusammenfassen statt vollständig mitsenden.
• Dokumente aufteilen und abschnittsweise verarbeiten.
• max_tokens setzen, damit die Antwort nicht den restlichen Platz sprengt.
• Für große Dokumentsammlungen ist eine App mit Wissensbasis der bessere Weg als das Einbetten in Prompts – siehe Was ist RAG?

Streaming-Fehler

Vor dem ersten Chunk erhalten Sie normale HTTP-Fehler. Danach zeigt sich ein Fehler als abgebrochener Stream ohne [DONE] – behandeln Sie das als unvollständige Antwort und wiederholen Sie mit Backoff. Details: Streaming.

Nutzern Fehler erklären

Zeigen Sie nie das rohe Token oder interne Details an. Sinnvolle Zuordnung:

Fehler	Meldung für Nutzer
401 / 403	„Die Verbindung zu basebox ist nicht autorisiert. Bitte wenden Sie sich an Ihren Administrator."
Kontext zu groß	„Die Anfrage ist zu umfangreich. Kürzen Sie den Text oder beginnen Sie eine neue Unterhaltung."
Zeitüberschreitung / 5xx	„basebox antwortet gerade nicht. Bitte versuchen Sie es in Kürze erneut."
Modell unbekannt	„Das gewählte Modell ist nicht verfügbar." – und intern /v1/models neu laden

Checkliste für die Fehlersuche

1. Header prüfen: Authorization: Bearer <token>, Content-Type: application/json, X-Realm.
2. JSON validieren; Rollen nur system, user, assistant, tool.
3. /v1/models abfragen – existiert das Modell genau so geschrieben?
4. Pfad prüfen: /v1/chat/completions, nicht /api/v1/….
5. Dieselbe Anfrage in Swagger UI (/v1/api/docs) ausführen – schlägt sie dort auch fehl?
6. Bei 5xx: Zeitpunkt notieren und den Support mit Anfrage (ohne Token) und Fehlerantwort kontaktieren. Auf basebox Server prüft der Platform Operator die aisrv-Logs und den Inferenz-Endpunkt.

Weiter: Troubleshooting im Benutzerhandbuch · Support kontaktieren