GLM-API-Fehler haben zwei Ebenen: außen den HTTP-Statuscode, innen den Geschäftsfehlercode im Antwortkörper. Wer nur außen schaut, deutet leicht falsch – auch ein offener Rechnungsbetrag kann als 429 zurückkommen. Die Prüfreihenfolge sollte lauten: zuerst Geschäftsfehlercode und Fehlermeldung lesen, dann Request-ID oder Fehler-ID suchen, mit einer minimalen Anfrage reproduzieren und erst zuletzt Parameter oder Modell ändern.
Dieser Artikel trennt 401, 403, 404, 429, 5xx und Timeouts, liefert eine Zuordnungstabelle der Geschäftsfehlercodes, Fehlerbehandlungscode und eine Checkliste vor der Kontaktaufnahme mit dem Support. Modelle und Preise stehen in den Modellpreisen.
Hinweis: Zhipu, GLM und BigModel sind Marken der jeweiligen Inhaber. Dieser Beitrag dient der technischen Erläuterung; es besteht keine Zugehörigkeit und keine Vertretungsbeziehung zu Zhipu. Fehlercodes, Drosselungsregeln und Schnittstellenverhalten können sich mit Versionen ändern; maßgeblich sind die offizielle Dokumentation und die tatsächliche Antwort.
1. Zuerst die zwei Fehlerebenen unterscheiden
Der HTTP-Statuscode beschreibt das Ergebnis auf Protokollebene, der Geschäftsfehlercode die konkrete Ursache. Derselbe 401 kann durch fehlenden Authentifizierungsheader, abgelaufenes Token oder Zwei-Faktor-Authentifizierung entstehen; derselbe 429 durch Drosselung, ausgelastetes Modell, offene Rechnung oder Tariflimit. Den Geschäftsfehlercode ins Log zu schreiben, ist der effizienteste erste Schritt der Fehlersuche.
| HTTP | Häufiger Geschäftsfehlercode | Bedeutung | Wiederholbar? |
|---|---|---|---|
| 401 | 1000 / 1001 / 1003 / 1005 | Authentifizierung fehlgeschlagen, Header fehlt, Token abgelaufen, Zwei-Faktor nötig | Nein, zuerst Zugangsdaten prüfen |
| 403 | 1220 | Kein Zugriff auf API oder Modell | Nein, Tarif und Rechte prüfen |
| 400 | 1210 / 1211 / 1221 / 1222 / 1261 | Parameterfehler, Modell nicht vorhanden, API abgeschaltet oder nicht vorhanden, Prompt zu lang | Nein, Anfrage ändern |
| 429 | 1113 | Offene Rechnung | Nein, zuerst aufladen |
| 429 | 1302 / 1305 | Rate Limit, Modell derzeit stark ausgelastet | Ja, mit Backoff |
| 429 | 1308 / 1310 | Periodenlimit, Reset laut next_flush_time | Auf Reset warten, nicht erzwingen |
| 429 | 1311 / 1313 / 1315 | Tarif ohne Modellrecht, Fair-Use-Limit, Key-Typ passt nicht | Nein, Tarif und Key prüfen |
| 500 | 1200 / 1230 / 1234 | Interner Fehler, Ablauffehler, Netzfehler (mit Fehler-ID) | Ja, Backoff und Fehler-ID sichern |
Die Tabelle zeigt die häufigsten Zuordnungen; die vollständige Liste steht in der offiziellen Dokumentation. Ein Streaming-Abbruch kann ohne Geschäftsfehlercode auftreten; die Ursache zeigt sich dann in finish_reason oder im letzten Datensatz.
2. 401: vier Arten von Authentifizierungsfehlern
401 bedeutet, dass die Identität nicht bestätigt wurde; mit Modellfähigkeit oder Guthaben hat das meist nichts zu tun. Die offiziellen Fehlercodes unterscheiden die häufigen Ursachen:
- 1000 Authentifizierung fehlgeschlagen: Key falsch, unvollständig kopiert oder gelöscht.
- 1001 Authentifizierungsparameter im Header fehlt: kein
Authorization: Bearer <key>, oder der Proxy verwirft ihn. - 1003 Token abgelaufen: Der Key hat eine Laufzeit oder wurde in der Konsole rotiert.
- 1005 Zwei-Faktor-Authentifizierung aktiv: Verifizierung nach Plattformvorgabe abschließen.
Prüfen Sie der Reihe nach:
- Header-Format bestätigen: ein Leerzeichen nach dem Doppelpunkt, keine Anführungszeichen oder Zeilenumbrüche um den Key.
- Das Präfix der Umgebungsvariable ausgeben und sicherstellen, dass sie nicht leer oder veraltet ist.
- Den Key-Typ prüfen: Standardmodell-API, Coding Plan sowie Team- oder Enterprise-Keys werden getrennt verwaltet und dürfen nicht gemischt werden.
- Prüfen, ob Base URL und Key zusammengehören: offizieller Key zur offiziellen Adresse, Gateway-Key zur Gateway-Adresse.
- Mit einem neuen Key eine minimale Anfrage senden, um Key-Probleme von Proxy- und Gateway-Konfiguration zu trennen.
Beim Kopieren aus einem Chatfenster gelangen besonders leicht Leerzeichen oder Zeilenumbrüche in den Key. Eine Anfrage, die nur ein Wort ausgeben soll, schließt viele einfache Fehler aus.
3. 403 und 404: Rechte, Pfad und Modellname
Der häufige Geschäftsfehlercode bei 403 ist 1220: Das aktuelle Konto darf nicht auf diese API oder dieses Modell zugreifen. Zuerst prüfen, ob der Tarif das Modell enthält und der Key zum passenden Produkttyp gehört, dann, ob eine nicht freigeschaltete Schnittstelle aufgerufen wird. Wiederholungen helfen hier nicht; Rechte ändern oder Key wechseln.
404 bedeutet meist nicht „Dienst ausgefallen“, sondern falsche Adresse: Bei der Base URL fehlt oder doppelt sich /v1, das SDK hängt den Pfad automatisch an, während zusätzlich der vollständige Pfad geschrieben wurde, oder Rewrite-Regeln des Reverse Proxy beschädigen den Pfad. Ein falscher GLM-Modellname führt üblicherweise zu 400 mit 1211; eine abgeschaltete oder nicht vorhandene API zu 1221 beziehungsweise 1222. Bei 404 also zuerst die Adresse prüfen, bei 1211 den Modellnamen.
Modellnamen richten sich nach offizieller Dokumentation und Preisseite; Versionsnummern nicht aus dem Gedächtnis schreiben. Vor einem Modellwechsel im Testsystem die Parameterkompatibilität bestätigen.
4. 429: zuerst den Geschäftsfehlercode lesen, dann über Wiederholung entscheiden
429 wird am häufigsten falsch behandelt. Mindestens fünf Fälle sind möglich:
- 1113 Offene Rechnung: Wiederholen vor der Aufladung ist sinnlos.
- 1302 Rate Limit erreicht: Parallelität senken oder Backoff.
- 1305 Modell derzeit stark ausgelastet: meist spitzenbedingt, mit Backoff wiederholen und bei Bedarf auf ein Ausweichmodell wechseln.
- 1308, 1310 Periodenlimit erreicht: Die Fehlermeldung enthält den Reset-Zeitpunkt; auf die Wiederherstellung des Kontingents warten.
- 1309, 1311, 1313, 1315: Tarif abgelaufen, Modell nicht freigeschaltet, Fair-Use-Limit oder falscher Key-Typ; nur eine Konfigurationsänderung hilft.
Nur vorübergehende Drosselungen wie 1302 und 1305 eignen sich für automatische Wiederholungen; in allen anderen Fällen verlängert Wiederholen die Störung nur. Die Drosselungsgrundlage – Parallelität, Anfragen pro Minute oder Token-Rate – variiert mit Tarif und Modell; maßgeblich sind Konsole und offizielle Dokumentation.
5. 5xx und Timeouts: getrennt eingrenzen
Die 500er-Reihe umfasst 1200 internen Fehler, 1230 Ablauffehler und 1234 Netzfehler. 1234 enthält meist eine Fehler-ID, die bei der Support-Kontaktaufnahme unbedingt gesichert werden sollte. Bei anhaltenden 5xx zuerst Backoff, dann Dienststatus oder Anbieterhinweise prüfen; nicht hochfrequent wiederholen.
Timeouts sind in drei Abschnitte zu trennen: Verbindungs-Timeout bedeutet DNS-, Ausgangs- oder Proxy-Problem; ein langsames erstes Token deutet auf Upstream-Warteschlange oder zu lange Eingabe; Lese-Timeout meist auf zu lange Ausgabe oder langes Reasoning. Die Behandlung unterscheidet sich; es reicht nicht, einfach alle Timeout-Werte zu erhöhen.
Bricht eine Streaming-Anfrage ab, kann sowohl HTTP-Fehlercode als auch Geschäftsfehlercode fehlen. Zuerst den empfangenen Inhalt und den letzten Datensatz speichern, finish_reason prüfen und dann zwischen Netzschwankung, Proxy-Abbruch und Upstream-Timeout unterscheiden. Halbe Inhalte nicht als vollständiges Ergebnis speichern.
6. Request-ID und Logs: Belege für die Fehlersuche
Nicht jede offizielle Antwort enthält an jeder Schnittstelle eine gleichnamige Request-ID; Feldnamen richten sich nach tatsächlicher Antwort und Dokumentation. Technisch stabiler ist eine doppelte Erfassung: Der Client erzeugt eine trace_id, die alle Wiederholungen begleitet, und der Upstream-Fehlerkörper wird unverändert inklusive aller request-id- und error-id-Felder gespeichert.
Das Log enthält mindestens: Zeitpunkt, trace_id, Base URL, Modellname, HTTP-Statuscode, Geschäftsfehlercode, Fehlermeldung, Laufzeit, Wiederholungszahl und ob gestreamt wurde. Vom Key nur die ersten Zeichen oder einen Hash speichern; Nutzertexte und vollständige Antworten nicht komplett ablegen.
Diese Felder dienen nicht nur der eigenen Analyse. Bei der Support-Kontaktaufnahme ist ein Datensatz mit trace_id, Geschäftsfehlercode und minimaler Reproduktion deutlich hilfreicher als „manchmal kommt ein Fehler“.
7. Retry und Backoff: Codebeispiel
Der folgende Code deaktiviert die automatische SDK-Wiederholung, entscheidet anhand des Geschäftsfehlercodes über eine Wiederholung und gibt trace_id, Statuscode und Geschäftsfehlercode gemeinsam aus. Netz-Timeouts werden separat behandelt; die Wiederholungen sind begrenzt.
import os
import random
import time
import uuid
import httpx
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError
client = OpenAI(
api_key=os.environ["GLM_API_KEY"],
base_url=os.environ.get(
"GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"
),
timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
max_retries=0, # automatische SDK-Wiederholung aus, die Logik unten steuert alles
)
RETRYABLE_CODES = {1302, 1305} # Rate Limit, Modell ausgelastet; offene Rechnung und Tariflimit nicht enthalten
def ask(prompt: str, max_attempts: int = 4) -> str:
trace_id = uuid.uuid4().hex[:12]
for attempt in range(1, max_attempts + 1):
try:
resp = client.chat.completions.create(
model=os.environ["GLM_MODEL"],
messages=[{"role": "user", "content": prompt}],
max_tokens=1024,
)
return resp.choices[0].message.content
except APIStatusError as exc:
code = None
try:
code = int(exc.response.json().get("code"))
except Exception:
pass
print(
f"trace={trace_id} attempt={attempt} "
f"http={exc.status_code} code={code} "
f"body={exc.response.text[:500]}"
)
retryable = exc.status_code >= 500 or (
exc.status_code == 429 and code in RETRYABLE_CODES
)
if not retryable or attempt == max_attempts:
raise
except (APITimeoutError, APIConnectionError) as exc:
print(f"trace={trace_id} attempt={attempt} err={type(exc).__name__}")
if attempt == max_attempts:
raise
wait = min(2 ** (attempt - 1), 20) + random.uniform(0, 1)
time.sleep(wait)
raise RuntimeError("Maximale Zahl der Wiederholungen erreicht")
Drei ergänzende Regeln: Ein vom Server gelieferter Retry-After hat Vorrang (falls vorhanden); das Wiederholungsbudget muss global begrenzt werden, damit sich mehrere Dienste nicht addieren; bei Anfragen mit Nebenwirkungen zuerst mit Idempotenzschlüssel den Status prüfen, dann über erneutes Senden entscheiden.
8. Parallelitätssteuerung: wirksamer als größere Retry-Zahlen
Drosselungsprobleme lassen sich meist nicht durch Wiederholungen lösen, sondern durch Steuerung am Eingang:
- Jeder Dienst erhält einen eigenen Key und eine eigene Parallelitätsobergrenze.
- Batch-Aufgaben aufteilen und zeitlich versetzen, um Verkehrsspitzen zur vollen Stunde zu vermeiden.
- Eine Queue glättet Spitzen; fehlgeschlagene Aufgaben wandern in eine Verzögerungswarteschlange statt im Kreis zu laufen.
- Anteil der 429 und P95-Latenz überwachen; bei sprunghaftem Anstieg zuerst Parallelität senken.
- Ausweichmodell oder Ausweicheinstieg bereithalten, vor dem Wechsel aber Parameterkompatibilität prüfen.
Parallelitätsobergrenze, Anfragen pro Minute und Token-Rate variieren mit Tarif und Modell; maßgeblich sind Konsole und offizielle Dokumentation. Zahlen anderer Teams nicht übernehmen, sondern anhand eigener Messungen setzen.
9. Checkliste vor der Kontaktaufnahme mit dem Support
- Zeitpunkt und Zeitzone, ob die Störung gebündelt auftrat.
- Base URL, Schnittstellenpfad, Modellname und Anfragemethode.
- HTTP-Statuscode, Geschäftsfehlercode und vollständige Fehlermeldung.
- Fehler-ID oder Request-ID; falls nicht vorhanden, die eigene
trace_id. - Eine reproduzierbare minimale curl-Anfrage mit maskiertem Key.
- Ob gestreamt wurde, langer Kontext beteiligt war oder die Konfiguration gerade geändert wurde.
- Auswirkungsbereich: einzelner Key, einzelnes Projekt oder alle Dienste.
Sind diese Punkte vollständig, kann der Support direkt eingrenzen, statt Informationen nachzufordern. Nach jeder Störung Monitoring und Alarme ergänzen, nicht auf Nutzerbeschwerden warten.
10. Häufige Fragen
Ist 429 immer eine Drosselung?
Nein. 429 kann auch offene Rechnung (1113), Periodenlimit (1308, 1310), fehlendes Modellrecht im Tarif (1311) oder Fair-Use-Limit (1313) bedeuten. Zuerst den Geschäftsfehlercode lesen, dann zwischen Backoff, Aufladung und Konfigurationsänderung entscheiden.
Was tun, wenn 401 auch mit neuem Key scheitert?
Prüfen, ob der Header Authorization: Bearer <key> lautet, die Umgebungsvariable geladen ist, Key-Typ und Schnittstelle zusammenpassen, Base URL und Key zusammengehören und der Reverse Proxy den Auth-Header nicht verwirft.
Sollten Timeouts wiederholt werden?
Nur Verbindungsfehler und Lese-Timeouts mit begrenzter Zahl und exponentiellem Backoff wiederholen. Bei Vorgängen mit Nebenwirkungen zuerst prüfen, ob sie bereits ausgeführt wurden, um doppelte Bestellungen oder Schreibvorgänge zu vermeiden.
Wie prüft man einen abgebrochenen Streaming-Ausgang?
Empfangenen Inhalt, letzten Datensatz und finish_reason speichern und zwischen Netzschwankung, Proxy-Abbruch und Upstream-Timeout unterscheiden. Der Client muss Wiederverbindung und Deduplizierung unterstützen; halbe Inhalte nicht speichern.
Was tun, wenn die Fehlermeldung nur einen Statuscode und keinen Geschäftsfehlercode enthält?
Vollständigen Antwortkörper und Antwortheader sichern, trace_id, Base URL, Modellname und minimale Reproduktion notieren und dann den Anbieter kontaktieren. Bei einem Gateway diese Angaben auch dem Gateway-Anbieter geben, damit er sie mit den Upstream-Logs abgleichen kann.
Nächster Schritt
Erstellen Sie zuerst im ZSQH AI Gateway einen Test-Key und spielen Sie 401, 403, 429, 5xx und einen Timeout je einmal durch, bevor Sie das Produktionsmonitoring anbinden. Verfügbare Modelle und Abrechnung stehen in den Modellpreisen.
