# Fehlercode-Referenz

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

| Code | Typ | Beschreibung | Schweregrad |
|------|------|-------------|----------|
| 400 | Client-Fehler | Ungültige Anfrage | Niedrig |
| 401 | Authentifizierungsfehler | Ungültiger API-Key | Mittel |
| 402 | Anbieterfehler | Upstream-Anbieter vorübergehend ablehnend | Mittel |
| 403 | Berechtigungsfehler | Zugriff verweigert | Mittel |
| 429 | Rate Limit | Zu viele Anfragen | Mittel |
| 500 | Serverfehler | Interner Fehler | Hoch |
| 502 | Gateway-Fehler | Upstream nicht verfügbar | Hoch |
| 503 | Dienst nicht verfügbar | Vorübergehend überlastet | Hoch |
| 529 | API überlastet | Claude API überlastet | Hoch |

---

## 429 - Too Many Requests

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

### Fehlermeldung

```text
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**:
```bash
# 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

```text
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**:
```bash
# 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

```text
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**:
```bash
# Check environment variable
echo $ANTHROPIC_AUTH_TOKEN

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

**Schritte**:

1. Im [QCode.cc Dashboard](https://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

```text
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](/docs/reference/faq)

### Was Sie tun können

**1. Modell wechseln (am wirksamsten)**

```bash
# Switch inside a session
/model sonnet

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

**2. Endpoint-Domain wechseln**

```bash
# 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](/docs/getting-started/endpoints-and-api-paths).

**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](javascript:void(Tawk_API.toggle())) oder [hi@qcode.cc](mailto: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](/docs/reference/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](/docs/reference/troubleshooting).

---

## 403 - Forbidden

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

### Fehlermeldung

```text
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

```bash
# 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](/docs/reference/troubleshooting) für die vollständige Vorgehensweise.

---
## 400 – Ungültige Anfrage

Falsches Anfrageformat oder ungültige Parameter.

### Fehlermeldung

```text
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

```bash
# 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

```text
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

```bash
# 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](https://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:

```text
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](/docs/usage/context-management).

---

## 503 – Dienst nicht verfügbar

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

### Fehlermeldung

```text
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

```bash
# 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

```text
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

```bash
# 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

```text
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

```bash
# 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

```text
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

```bash
# 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

```bash
# 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

```bash
# 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

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

### 3. Detaillierte Protokollierung aktivieren

```bash
# Use verbose mode for detailed info
claude --verbose

# Or set debug mode
DEBUG=true claude
```

### 4. Einfache Anfrage testen

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

### 5. Servicestatus prüfen

Besuchen Sie [QCode.cc](https://qcode.cc) für Statusmeldungen zum Dienst.

---

## Bewährte Praktiken für die Fehlerbehandlung

### Wiederholungsmechanismus implementieren

```bash
# 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](https://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)