Fehlercode-Referenz

Referenz für QCode.cc API-Fehlercodes: 400/401/402/403/429/500/502/503/529 Bedeutung, typische Ursachen und bewährte Lösungen, einschließlich INSUFFICIENT_BALANCE

Dieses Dokument enthält ausführliche Informationen zu verschiedenen Fehlercodes, die Sie bei der Nutzung von Claude Code antreffen können, sowie deren Lösungen.

Fehlercode-Schnellreferenz¶

429 - Too Many Requests¶

Einer der häufigsten Fehler. Er zeigt an, dass in einem kurzen Zeitraum zu viele Anfragen gestellt wurden.

Fehlermeldung¶

Error: 429 Too Many Requests
Rate limit exceeded. Please slow down your requests.

Häufige Ursachen¶

1. Zu häufige Anfragen: Mehrere Anfragen in schneller Abfolge senden

2. Zu viele gleichzeitige Anfragen: Mehrere Claude Code Instanzen parallel ausführen

3. Token-Limit erreicht: Zu viele Tokens in kurzer Zeit verbrauchen

4. Kontingent erschöpft: Tägliches/monatliches Kontingent aufgebraucht

Lösungen¶

Sofortmaßnahmen:

# Wait 30-60 seconds before retrying
sleep 60 && claude "your question"

Langfristige Lösungen:

1. Anfragefrequenz reduzieren, schnelle aufeinanderfolgende Anfragen vermeiden

2. Den Befehl /compact verwenden, um den Kontext zu komprimieren

3. Große Aufgaben in kleinere Teilschritte aufteilen

4. Upgrade auf einen Tarif mit höherem Kontingent in Erwägung ziehen

Vorteil bei QCode.cc: Professionelles Load Balancing mit Multi-Account-Pools verteilt die Anfragelast und reduziert 429-Fehler effektiv.

502 - Bad Gateway¶

Zeigt an, dass das Gateway oder der Proxy-Server eine ungültige Antwort vom Upstream-Anbieter erhalten hat.

Fehlermeldung¶

Error: 502 Bad Gateway
The server received an invalid response from the upstream server.

Häufige Ursachen¶

1. Upstream vorübergehend nicht verfügbar: Probleme mit dem Anthropic API-Server

2. Netzwerkverbindung unterbrochen: Verbindung bricht während der Anfrage ab

3. Proxy-Server-Probleme: Ausfall eines Zwischenknotens

4. Zeitüberschreitung der Anfrage: Antwortzeit überschreitet das Gateway-Limit

Lösungen¶

Sofortmaßnahmen:

# Check network connection
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Wait and retry
sleep 30 && claude "your question"

Langfristige Lösungen:

1. Lokale Netzwerkstabilität prüfen

2. Andere Netzwerkumgebung ausprobieren

3. VPN oder stabileres Netzwerk verwenden

4. Bei anhaltenden Problemen den Support kontaktieren

Vorteil bei QCode.cc: Multi-Region-Bereitstellung, CDN-Beschleunigung und automatisches Failover gewährleisten 99,9 % Verfügbarkeit.

401 - Unauthorized¶

Ungültiger API-Key oder fehlende gültige Authentifizierung.

Fehlermeldung¶

Error: 401 Unauthorized
Invalid API key or authentication token.

Häufige Ursachen¶

1. Falscher API-Key: Fehlende Zeichen oder zusätzliche Leerzeichen beim Kopieren

2. Abgelaufener API-Key: Das Abo ist abgelaufen

3. Deaktivierter API-Key: Wegen Richtlinienverstoß gesperrt

4. Umgebungsvariable nicht gesetzt: ANTHROPIC_AUTH_TOKEN nicht konfiguriert

Lösungen¶

API-Key überprüfen:

# Check environment variable
echo $ANTHROPIC_AUTH_TOKEN

# Confirm correct format (starts with cr_)
# Correct example: cr_xxxxxxxxxxxxxxxxxxxx

Schritte:

1. Im QCode.cc Dashboard anmelden und den API-Key-Status prüfen

2. Sicherstellen, dass das Abo aktiv ist

3. Bei Sperrung den Support kontaktieren (QCode.cc bietet sofortigen Ersatzservice)

402 - Payment Required¶

Der vorgeschaltete Anbieter hat diese Anfrage abgelehnt. Das ist in der Regel kein Problem mit Ihrem API-Key oder Ihrer Konfiguration — Anfragen desselben API-Keys an andere Modelle funktionieren zur gleichen Zeit normalerweise einwandfrei.

Was Sie sehen¶

Error: 402 Payment Required

In Claude Code sieht es üblicherweise so aus, als würde die Anfrage einfach fehlschlagen, ohne Antwortinhalt; aus einem Skript oder SDK erhalten Sie HTTP 402.

Häufige Ursachen¶

1. Der vorgeschaltete Anbieter ist vorübergehend nicht verfügbar: Das QCode-Gateway erzeugt selbst niemals einen 402 — es leitet den vom vorgeschalteten Anbieter zurückgegebenen Status weiter

2. Konzentration auf ein einzelnes Modell: In einem bestimmten Moment kann ein Modell eine hohe 402-Rate aufweisen, während die anderen völlig einwandfrei sind

3. Abhängig von der Endpoint-Domain: Unterschiedliche Domains leiten über unterschiedliche vorgeschaltete Pfade, und die Wahrscheinlichkeit, einen 402 zu erhalten, kann erheblich variieren

4. Kein Bezug zu Ihrem Guthaben: Ein aufgebrauchtes Kontoguthaben oder ein erschöpftes Plan-Kontingent liefert keinen 402 — in diesem Fall heißt es „daily cost limit reached“, siehe FAQ

Was Sie tun können¶

1. Modell wechseln (am wirksamsten)

# Switch inside a session
/model sonnet

# Or specify at launch
claude --model claude-sonnet-5

2. Endpoint-Domain wechseln

# Mainland China
export ANTHROPIC_BASE_URL=https://asia.qcode.cc/api

# Global (Route 53 picks the nearest node)
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api

Alle drei Domains akzeptieren denselben API-Key, daher ist beim Wechsel keine weitere Konfigurationsänderung nötig. Siehe Endpoints & API Formats.

3. Keinen engen Retry-Loop schreiben

Ein 402 verschwindet nicht durch sofortiges erneutes Senden; ständiges Nachfragen verschlimmert es nur. Verwenden Sie exponentielles Backoff oder wechseln Sie einfach das Modell — siehe „Best Practices für Fehlerbehandlung“ auf dieser Seite.

4. Bei anhaltendem Problem: Support kontaktieren

Geben Sie den Zeitpunkt des Auftretens, die Modell-ID und die Endpoint-Domain an, und kontaktieren Sie uns über Live-Chat oder hi@qcode.cc.

INSUFFICIENT_BALANCE / Insufficient account balance¶

Manche 402/403-Antworten enthalten JSON wie "code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance". Das bedeutet nicht, dass Ihr QCode-Guthaben aufgebraucht ist. Es ist ein vorübergehender Zustand eines vorgeschalteten Kanals, der unverändert durchgereicht wird — unabhängig von Ihrem Konto. Wenn Ihr eigenes Kontingent erschöpft ist, lautet die tatsächlich angezeigte Meldung „Daily cost limit reached“ (siehe FAQ).

Vorgehensweise: Warten und erneut versuchen / Modell wechseln / Zugriff-Domain wechseln (die Schritte ①–③ oben treffen alle zu); bei anhaltendem Problem den Support mit der Request-ID kontaktieren. Vollständige Checkliste: Fehlerbehebungsanleitung.

403 - Forbidden¶

Anfrage vom Server abgelehnt, in der Regel aufgrund unzureichender Berechtigungen.

Fehlermeldung¶

Error: 403 Forbidden
You don't have permission to access this resource.

Häufige Ursachen¶

1. Falscher API-Endpoint: Verwendung einer inkorrekten API-Adresse

2. Unzureichende Berechtigungen: Der aktuelle Plan unterstützt diese Funktion nicht

3. Regionale Einschränkungen: Manche Funktionen sind in bestimmten Regionen nicht verfügbar

4. Probleme mit dem Kontostatus: Konto eingeschränkt

Lösungen¶

# Confirm API endpoint is correct
echo $ANTHROPIC_BASE_URL
# Should be: https://api.qcode.cc/api

1. API-Endpoint-Konfiguration überprüfen

2. Sicherstellen, dass der Plan die benötigten Funktionen enthält

3. Support kontaktieren, um Berechtigungen zu überprüfen

INSUFFICIENT_BALANCE (wird bei einem 403 angezeigt)¶

Wenn ein 403-Forbidden-Body INSUFFICIENT_BALANCE / Insufficient account balance enthält, handelt es sich auch hier in der Regel um einen vorübergehenden Zustand eines vorgeschalteten Kanals, der unverändert durchgereicht wird — nicht um eine Einschränkung Ihres Kontos. Gehen Sie wie im gleichnamigen Abschnitt des 402-Kapitels vor; siehe die Fehlerbehebungsanleitung für die vollständige Vorgehensweise.

400 – Ungültige Anfrage¶

Falsches Anfrageformat oder ungültige Parameter.

Fehlermeldung¶

Error: 400 Bad Request
The request was malformed or contained invalid parameters.

Häufige Ursachen¶

1. Fehlerhafte Anfrage: Falsches JSON-Format

2. Fehlende Parameter: Erforderliche Parameter wurden nicht angegeben

3. Ungültige Werte: Parameterwerte liegen außerhalb des zulässigen Bereichs

4. Kodierungsprobleme: Sonderzeichen sind nicht korrekt kodiert

Lösungen¶

# Check for special characters in input
# Ensure request content is properly formatted
claude -p "simple test"

1. Vereinfachen Sie die Eingabe und verzichten Sie auf Sonderzeichen

2. Stellen Sie sicher, dass Dateipfade die korrekte Kodierung verwenden

3. Prüfen Sie das Format der Befehlsparameter

500 – Interner Serverfehler¶

Der Server ist auf einen unerwarteten Zustand gestoßen, der die Bearbeitung der Anfrage verhindert hat.

Fehlermeldung¶

Error: 500 Internal Server Error
An unexpected error occurred on the server.

Häufige Ursachen¶

1. Serverseitiger Fehler: Problem im Code des API-Servers

2. Erschöpfte Ressourcen: Die Serverressourcen sind vorübergehend aufgebraucht

3. Konfigurationsfehler: Fehlerhafte Serverkonfiguration

Lösungen¶

# Wait and retry
sleep 60 && claude "your question"

# Use verbose mode for more info
claude --verbose

1. Warten Sie einige Minuten und versuchen Sie es erneut

2. Prüfen Sie den Dienststatus von QCode.cc

3. Wenden Sie sich bei anhaltendem Problem mit den Fehlerdetails an den Support

E015 – Überlauf des Konversationskontexts¶

Wird ausgelöst, wenn sich der Konversationskontext der Kapazitätsgrenze des Modells nähert (~95 %). QCode.cc gibt diesen Fehler als 429-Antwort zurück, um einen erneuten Versuch auszulösen:

429 {"error":{"code":"E015","message":"Internal server error"},"status":500}

Lösung: Lesen Sie den Abschnitt „Vermeidung von Überläufen bei langen Sitzungen“ in Kontextverwaltung.

503 – Dienst nicht verfügbar¶

Der Server kann Anfragen vorübergehend nicht verarbeiten, meist wegen Überlastung oder Wartungsarbeiten.

Fehlermeldung¶

Error: 503 Service Unavailable
The service is temporarily unavailable. Please try again later.

Häufige Ursachen¶

1. Serverüberlastung: Das Anfragevolumen übersteigt die Kapazität

2. Geplante Wartung: Der Server wird gewartet

3. Erschöpfte Ressourcen: Die Serverressourcen reichen vorübergehend nicht aus

Lösungen¶

# Use exponential backoff retry
for i in 1 2 4 8 16; do
  claude "your question" && break
  echo "Retrying, waiting ${i} seconds..."
  sleep $i
done

1. Warten Sie einige Minuten und versuchen Sie es erneut

2. Verwenden Sie eine Retry-Strategie mit exponentiellem Backoff

3. Prüfen Sie die Statusmeldungen zum Dienst

529 – Überlastet¶

Ein Claude-API-spezifischer Fehlercode, der eine Überlastung des API-Dienstes anzeigt.

Fehlermeldung¶

Error: 529 Overloaded
The API is temporarily overloaded. Please try again later.

Häufige Ursachen¶

1. Globaler Nutzungsanstieg: Sprunghafter Anstieg der Nutzerzahlen beim Claude-Dienst weltweit

2. Stoßzeiten: Gebündelte Anfragen während der Arbeitszeiten

3. Beliebte Ereignisse: Bestimmte Ereignisse führen zu einem Nutzungsanstieg

Lösungen¶

# Retry later
sleep 120 && claude "your question"

1. Warten Sie 2–5 Minuten und versuchen Sie es erneut

2. Vermeiden Sie Stoßzeiten (US-Geschäftszeiten)

3. Verwenden Sie /compact, um die Token-Nutzung zu verringern

Vorteil von QCode.cc: Der Rotationsmechanismus des Multi-Account-Pools verteilt die Überlastung wirksam.

Verbindungs-Timeout¶

Die Anfrage konnte nicht innerhalb der vorgegebenen Zeit abgeschlossen werden.

Fehlermeldung¶

Error: Connection timed out
The request timed out while waiting for a response.

Häufige Ursachen¶

1. Instabiles Netzwerk: Schlechte Qualität der Netzwerkverbindung

2. Zu große Anfrage: Zu viele Kontext-Tokens

3. Zu komplexe Aufgabe: Die KI-Verarbeitung dauert zu lange

4. Langsame Serverantwort: Hohe Serverlast

Lösungen¶

# Test network connection
ping api.qcode.cc

# Use compact mode to reduce context
/compact

1. Prüfen Sie die Stabilität Ihrer Netzwerkverbindung

2. Verwenden Sie /compact, um den Kontext zu komprimieren

3. Teilen Sie komplexe Aufgaben in einfachere auf

4. Versuchen Sie es in einer stabileren Netzwerkumgebung

MCP-Server-Fehler¶

Fehler, die aus der Konfiguration oder dem Betrieb eines MCP-Servers resultieren können.

Symptome¶

MCP server "xxx" failed to start
MCP connection timed out
MCP tool execution failed

Häufige Ursachen¶

1. Falscher Serverbefehl: Tippfehler im npx-Paketnamen oder Paket nicht installiert

2. Fehlende Umgebungsvariablen: Das vom MCP-Server benötigte Token ist nicht gesetzt

3. Timeout: Der Start oder die Ausführung des Servers dauert zu lange

4. Unzureichende Berechtigungen: Dateisystem-/Datenbankzugriff verweigert

Lösungen¶

# Check server status with /mcp
/mcp

# Diagnose configuration issues with /doctor
/doctor

# Manually test whether the MCP server can start
npx -y @modelcontextprotocol/server-filesystem /tmp

1. Verbindungsstatus mit /mcp prüfen

2. Automatische Diagnose mit /doctor ausführen

3. Format von ~/.claude/settings.json oder .mcp.json überprüfen

4. Sicherstellen, dass erforderliche Umgebungsvariablen gesetzt sind ($GITHUB_TOKEN usw.)

5. Timeouts über die Umgebungsvariablen MCP_TIMEOUT und MCP_TOOL_TIMEOUT erhöhen

Allgemeine Fehlerbehebungsschritte¶

Bei einem beliebigen Fehler gehen Sie wie folgt vor:

0. Automatische Diagnose ausführen¶

# Claude Code's built-in diagnostic tool
/doctor

Dies prüft automatisch häufige Konfigurationsprobleme: Umgebungsvariablen, API-Konnektivität, MCP-Server-Status und mehr.

1. Netzwerkverbindung prüfen¶

# Test API endpoint connectivity
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# Test DNS resolution
nslookup api.qcode.cc

2. Umgebungsvariablen überprüfen¶

# Check all relevant environment variables
echo "BASE_URL: $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:0:10}..."

3. Detaillierte Protokollierung aktivieren¶

# Use verbose mode for detailed info
claude --verbose

# Or set debug mode
DEBUG=true claude

4. Einfache Anfrage testen¶

# Send simple test request
claude -p "say hello"

5. Servicestatus prüfen¶

Besuchen Sie QCode.cc für Statusmeldungen zum Dienst.

Bewährte Praktiken für die Fehlerbehandlung¶

Wiederholungsmechanismus implementieren¶

# Simple retry script
retry_claude() {
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    claude "$@" && return 0
    echo "Attempt $attempt failed, retrying..."
    sleep $((attempt * 2))
    ((attempt++))
  done

  echo "All attempts failed"
  return 1
}

Nutzung überwachen¶

Prüfen Sie die API-Nutzung regelmäßig, um eine Überschreitung des Kontingents zu vermeiden:

1. Anmelden im QCode.cc Dashboard

2. Nutzungsstatistik einsehen

3. Nutzungswarnungen konfigurieren

Anfragen optimieren¶

1. Kontext reduzieren: Regelmäßig /compact oder /clear verwenden

2. Stapelverarbeitung: Große Aufgaben in kleinere aufteilen

3. Duplikate vermeiden: Häufige Ergebnisse cachen

Hilfe erhalten¶

Falls die obigen Lösungen Ihr Problem nicht beheben, kontaktieren Sie den QCode.cc-Support:

• Live-Chat: Unten rechts auf der Website

• Antwortzeit: 1–2 Stunden zu den Geschäftszeiten

• Supportzeiten: 7×14 (täglich 9:00–23:00 Uhr)

Wenn Sie den Support kontaktieren, geben Sie bitte Folgendes an:

1. Vollständige Fehlermeldung

2. Ausgeführter Befehl

3. Zeitpunkt des Auftretens

4. Präfix des API-Keys (geben Sie niemals den vollständigen Key weiter)