Nach dem Anschluss einer eigenen API an Chatbox sind Fehler meist nicht „das Modell ist kaputt“, sondern fallen in vier Kategorien: Identität stimmt nicht, Adresse oder Modell stimmt nicht, Kontingent oder Parallelität ist erschöpft, Netzwerk oder TLS ist gestört. Erst klassifizieren, dann prüfen – das ist deutlich effektiver als wiederholtes Neuinstallieren.

Dieser Artikel behandelt 401, 404 (einschließlich model not found), 429 und Verbindungsfehler und ergänzt Streaming-Abbrüche, Konfigurations-Sync zwischen Geräten sowie Log-Auswertung. Menünamen richten sich nach der aktuellen Chatbox-Version, Modelle und Preise nach den Modellpreisen.

Hinweis: Chatbox ist ein Produkt und eine Marke seines jeweiligen Inhabers. Dieser Artikel dient nur der technischen Fehlersuche und begründet keine Zugehörigkeit; Feldnamen und Standardwerte können sich zwischen Versionen unterscheiden.

1. Zuerst Beweise sichern, dann die Kategorie bestimmen

Symptom Häufiger Statuscode oder Fehler Erste Einschätzung Zuerst prüfen
401 Unauthorized invalid_api_key, leere Antwort Key oder Request-Header Ist der Key vollständig und gehört er zu dieser Adresse?
404 / model not found not_found_error Pfad oder Modell-ID Host, API-Pfad, Modell-ID
429 Too Many Requests rate_limit_error, insufficient_quota Rate-Limit oder Guthaben Verbrauch, Parallelität, Rechnung
Failed to fetch / Network Error kein Statuscode Netzwerk nicht erreichbar DNS, Proxy, Firewall, TLS
5xx server_error Upstream- oder Gateway-Störung Wiederholen und Request-ID notieren

Notieren Sie vor der Fehlersuche Zeitpunkt, Chatbox-Version, HTTP-Statuscode, Antwortkörper und Request-ID. Ohne diese Angaben bleibt nur Raten; mit ihnen lässt sich bestimmen, ob das Problem im Client, im Netzwerk oder beim Dienst liegt.

2. 401: Der Key wird nicht erkannt

401 bedeutet, dass der Server den Key nicht akzeptiert. Häufige Ursachen:

  • Beim Kopieren sind Leerzeichen, Zeilenumbrüche oder Vollbreitenzeichen hineingeraten; nach dem Einfügen sieht alles gleich aus, ist es aber nicht.
  • Der Lizenzschlüssel von Chatbox AI wurde als API-Key in den benutzerdefinierten Anbieter eingetragen.
  • Der Key wurde gelöscht oder rotiert, oder das zugehörige Projekt wurde deaktiviert.
  • Es wird der Key von Anbieter A gegen die Adresse von Anbieter B gesendet.
  • Die Anfrage läuft über einen Firmenproxy, der eine 401-Anmeldeseite als HTML statt JSON zurückgibt.

Prüfen Sie zuerst, ob als API-Modus „OpenAI-kompatibel“ gewählt ist, und fügen Sie den Key erneut ein. Verlassen Sie sich nicht auf „sieht gleich aus“, sondern testen Sie am Client vorbei:

export ZSQH_API_KEY="sk-Ihr-Schluessel"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"Ihre-Modell-ID","messages":[{"role":"user","content":"Antworte nur mit OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Eine Antwort mit 200 und choices belegt, dass Key und Adresse gültig sind. Bleibt es bei 401, liegt die Ursache in der Key-Kopie, den Rechten oder dem Proxy. Ein 403 bedeutet meist „du bist erkannt, darfst dieses Modell aber nicht nutzen“ – nicht mit 401 verwechseln und wiederholt Keys tauschen.

3. 404 und model not found: Adresse und Modell getrennt prüfen

404 hat zwei Varianten: Der Pfad existiert nicht, oder das Modell existiert nicht. Erstere betrifft die URL, letztere die Modell-ID. Chatbox trägt API-Host und API-Pfad getrennt ein; der häufigste Fehler ist ein doppeltes /v1: Der Host endet bereits auf /v1, der Pfad enthält aber erneut /v1/chat/completions, sodass die Anfrage bei /v1/v1/chat/completions landet.

Die Prüfregel ist einfach: In der endgültigen Anfrageadresse darf /v1 nur einmal vorkommen. Lautet der Host https://ai.zhongshangqihang.com, kann der Pfad leer bleiben oder nach der aktuellen Dokumentation ausgefüllt werden; endet der Host auf .../v1, darf der Pfad es nicht wiederholen. Nach der Änderung speichern und mit „Prüfen“ oder curl erneut testen.

model_not_found hat nichts mit dem Pfad zu tun. Modell-IDs unterscheiden Groß-/Kleinschreibung, Versionssuffixe und Anbieterpräfixe und müssen aus den Modellpreisen oder der Konsole kopiert werden. Beim manuellen Hinzufügen außerdem prüfen, ob der Modelltyp „Chat“ ist und die aktivierten Fähigkeiten der Realität entsprechen; sonst erscheint das Modell nicht oder schlägt beim ersten Aufruf fehl.

Auch ein fehlgeschlagenes „Modellliste abrufen“ bedeutet nicht zwingend einen Konfigurationsfehler. Manche Gateways bieten keine Modelllisten-Schnittstelle; mit einer korrekt eingetragenen Modell-ID funktioniert der Chat trotzdem.

4. 429: Rate-Limit, Parallelität und Guthaben

429 hat zwei Bedeutungen: zu schnell angefragt oder kein Guthaben. OpenAI-kompatible Schnittstellen verwenden häufig rate_limit_error für Ersteres und insufficient_quota für Letzteres. Beides kann als 429 erscheinen, erfordert aber entgegengesetzte Reaktionen.

  • Zu schnell: Parallelität senken, weniger gleichzeitige Sitzungen und Clients; langer Kontext erhöht den Token-Verbrauch.
  • Kein Guthaben: Verbrauch und Rechnung im Gateway prüfen, aufladen oder Key wechseln; reines Wiederholen hilft nicht.
  • Enthält der Antwort-Header Retry-After, warten Sie entsprechend; sonst exponentielles Backoff mit zufälligem Jitter verwenden.
  • In Chatbox nicht wiederholt „Prüfen“ anklicken oder Nachrichten sofort erneut senden; kurzfristig summieren sich die Anfragen.
  • Wird derselbe Key auf mehreren Geräten und in mehreren Fenstern genutzt, teilen sie sich das Parallelitätskontingent.

Tritt 429 nur bei langen Gesprächen auf, zuerst den Kontext kürzen oder eine neue Sitzung beginnen und dann das Kontextfenster des Modells prüfen. Die Einstellung „maximale Kontextnachrichten“ lässt sich senken, mildert aber nur den Kontextdruck und ersetzt kein Verbrauchs- und Parallelitätsmanagement.

5. Verbindungsfehler: DNS, Proxy, SSL und Firewall

Failed to fetch, Network Error oder endloses Laden bedeuten, dass keine gültige Antwort ankam. Prüfen Sie zuerst, ob der Browser die Seite öffnen kann, und testen Sie dieselbe Domain mit curl. Scheitert curl ebenfalls, liegt es an Netzwerk oder Gateway; funktioniert curl, aber Chatbox nicht, liegt es meist an Client-Proxy, Pfadzusammensetzung oder Zertifikatsvertrauen.

  • Firmennetz: Firewall oder Security-Gateway können fremde Domains blockieren; die IT muss sie freigeben.
  • Proxy: Systemproxy, VPN und der Proxy-Schalter in Chatbox können sich überlagern; nur eine Ebene aktiv lassen und die Proxy-Adresse nicht in den API-Host schreiben.
  • TLS: self signed certificate, UNABLE_TO_VERIFY_LEAF_SIGNATURE oder abgelaufene Zertifikate treten häufig bei Firmen-Entschlüsselungsproxys auf; das Unternehmens-Stammzertifikat installieren, statt die Prüfung abzuschalten.
  • Systemzeit: Eine große Abweichung lässt die Zertifikatsprüfung scheitern.
  • Mobilnetz: Unterschiedliche Ergebnisse zwischen WLAN und Mobilfunk deuten auf lokales Netzwerk oder DNS hin.

Tritt der Fehler nur auf einem Rechner auf, vergleichen Sie zuerst Systemproxy, hosts-Datei, DNS und Zertifikate, bevor Sie das Modell verdächtigen.

6. Streaming-Abbrüche und „die Antwort bleibt auf halber Strecke stehen“

Chatbox nutzt standardmäßig Streaming. Ein Abbruch tritt typischerweise in drei Fällen auf: Proxy oder Gateway puffern SSE, die Verbindung läuft in ein Idle-Timeout, oder der Upstream trennt während der Generierung. Die erste Hälfte erscheint normal, die zweite endet plötzlich, oder die Anzeige bleibt bei „tippt gerade“.

Schalten Sie zum Testen das Streaming ab, sofern die Version diese Option bietet, und stellen Sie dieselbe Frage erneut. Kommt die nicht gestreamte Antwort vollständig an, liegt das Problem in der SSE-Kette; prüfen Sie Puffereinstellungen, Timeouts und Netzwerkstabilität des Proxy. Lange Antworten, Reasoning-Modelle und Stoßzeiten lösen das Problem häufiger aus; kürzen Sie die Ausgabe oder versuchen Sie es zu einem anderen Zeitpunkt.

Reasoning-Modelle „denken“ außerdem unter Umständen lange, bevor sie Text ausgeben, was wie ein Hänger wirkt. Warten Sie zunächst ab und bestätigen Sie dann mit einer nicht gestreamten Anfrage, ob wirklich keine Antwort kommt.

7. Mehrere Geräte, Sitzungen und Konfigurations-Sync

Sitzungen und Einstellungen von Chatbox liegen standardmäßig lokal. Fehlt der Verlauf nach einem Rechner- oder Handywechsel, ist meist nicht die API defekt, sondern die Daten wurden nicht übertragen. Nutzen Sie zum Migrieren die Export-, Import- oder Backup-Funktion des Clients; der Funktionsumfang hängt von der Version ab.

Neuere Chatbox-Versionen können Modellanbieter-Konfigurationen im JSON-Format importieren und so Host, Modellliste und Fähigkeiten auf ein anderes Gerät übertragen. API-Keys sollten dennoch separat verwaltet werden: Keys pro Gerät oder Person vergeben, damit bei einer Offenlegung nur einer widerrufen werden muss.

Verhalten sich zwei Geräte unterschiedlich, vergleichen Sie zuerst Version, Systemproxy und Modellkonfiguration und erst danach die Keys. Aus „auf dem anderen Gerät geht es“ folgt nicht automatisch, dass das aktuelle Gerät ein Netzwerkproblem hat.

8. Logs und Beweissicherung: Das Problem klar beschreiben

Log- und Diagnosezugänge unterscheiden sich zwischen Chatbox-Versionen; manche bieten einen Export in den Einstellungen, andere erfordern Systemlogs. Unabhängig davon sollten Sie folgende Angaben manuell festhalten:

  • Zeitpunkt (mit Zeitzone) und ob der Fehler stabil reproduzierbar ist;
  • Chatbox-Version, Betriebssystem und Netzwerkumgebung;
  • HTTP-Statuscode und vollständiger Antwortkörper (Key entfernen);
  • Request-ID aus den Antwort-Headern;
  • curl-Ergebnis derselben Anfrage sowie Vergleich zwischen Streaming und Nicht-Streaming.

Beim Melden eines Problems den Key maskieren, aber Modell-ID, Zeitpunkt und Statuscode behalten. „Es verbindet nicht“ reicht meist nicht zur Lokalisierung; mit diesen Angaben lässt sich die Richtung oft in einer Runde bestimmen.

9. Eine feste Prüfreihenfolge

  1. Mit curl direkt das Gateway anfragen und prüfen, ob Key, Host und Modell gültig sind.
  2. Scheitert curl: DNS, Proxy, TLS, Firewall und Gateway-Status prüfen.
  3. Funktioniert curl, aber Chatbox nicht: API-Typ, doppeltes /v1, Modell-ID und Client-Proxy prüfen.
  4. 401 über den Key, 404 über Pfad und Modell, 429 über Verbrauch und Parallelität, Verbindungsfehler über Netzwerk und Zertifikate eingrenzen.
  5. Jeweils nur eine Variable ändern, sofort erneut testen und das Ergebnis notieren.

Der Wert dieser Reihenfolge liegt darin, „Client-Problem“ und „Dienst-Problem“ zu trennen. Die meisten sogenannten Chatbox-Fehler lassen sich am Ende auf eine Konfiguration oder eine Netzwerkebene zurückführen.

Für einheitliche Verwaltung von Keys, Verbrauch und Modelleinstieg können Sie sich beim ZSQH AI Gateway registrieren; verfügbare Modelle und Abrechnung entnehmen Sie den Modellpreisen. Preise können sich ändern; maßgeblich ist die Anzeige zum Zeitpunkt der Buchung.

Häufige Fragen

Bedeutet „Failed to fetch“ in Chatbox, dass der Key falsch ist?

Nicht unbedingt. Die Meldung besagt nur, dass der Client keine Antwort erhalten hat; ein falscher Key ist eine mögliche Ursache. Testen Sie denselben Host zuerst mit curl; scheitert auch curl, prüfen Sie vorrangig Netzwerk, Proxy und Zertifikate.

Warum funktioniert curl, Chatbox aber nicht?

Häufige Ursachen sind Client-Proxy, doppeltes /v1, falsch gewählter API-Typ, nicht vertrauenswürdiges Systemzertifikat oder eine andere Pfadzusammensetzung in der Clientversion. Vergleichen Sie die endgültige Anfrageadresse Punkt für Punkt.

Erholt sich 429 durch wiederholtes Versuchen?

Bei einem Rate-Limit können Backoff und weniger Parallelität helfen; bei fehlendem Guthaben bringt Wiederholen nichts, prüfen Sie Rechnung oder Key. Sehen Sie zuerst auf den Fehlertyp im Antwortkörper.

Kann man Modelle manuell hinzufügen, wenn die Modellliste nicht abrufbar ist?

Ja. Manche Gateways bieten keine Modelllisten-Schnittstelle; mit einer korrekten Modell-ID funktioniert der Chat trotzdem. Voraussetzung ist, dass Modell-ID, API-Typ und Host stimmen.

Werden Sitzungen und Konfiguration nach einem Gerätewechsel automatisch synchronisiert?

Sitzungen liegen standardmäßig lokal und werden nicht zwingend automatisch synchronisiert. Nutzen Sie Export und Import; neuere Versionen können Anbieter-JSONs importieren, aber API-Keys sollten neu eingetragen und separat verwaltet werden.

Weitere Artikel: