Claude-Code-Fehler erklärt — 401, 429, 529 und Installationsfehler unterscheiden

Claude-Code-Fehler fallen in zwei große Kategorien, und die meisten Suchergebnisse behandeln nur eine davon. Clientfehler während Installation und Ausführung sowie API-Fehler beim Aufruf des Modells haben völlig unterschiedliche Ursachen und Lösungen. Dieser Artikel konzentriert sich auf die zweite Kategorie — 401, 429 und 529 —, weil dies die Fehler sind, auf die Sie beim Wechsel von einem Abonnement zu einem API-Schlüssel zuerst stoßen.

Die Fehlerzeichenfolgen erscheinen in jedem Land auf Englisch. Im Folgenden bleiben die Zeichenfolgen im Original; nur die Erläuterungen sind auf Koreanisch verfasst.

Die Ursache zuerst in 30 Sekunden in drei Gruppen aufteilen

Senden Sie vor Änderungen an den Einstellungen einmal direkt eine Anfrage an den Endpunkt. Dieser eine Test unterscheidet zwischen „Clientproblem / Authentifizierungsproblem / Serverproblem“.

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

401 — der Header ist falsch, nicht der Schlüssel

Wenn 401 auch nach mehrmaliger Ausstellung eines neuen Schlüssels weiterhin auftritt, prüfen Sie nicht den Wert, sondern die Art der Übermittlung. Claude Code sendet ANTHROPIC_AUTH_TOKEN im Header Authorization: Bearer und ANTHROPIC_API_KEY im Header x-api-key. Gateways erwarten meist die erste Variante; wenn Sie die beiden Variablen vertauschen, tritt auch mit einem gültigen Schlüssel ein 401-Fehler auf.

Es kommt häufig vor, dass beide Variablen gleichzeitig gesetzt sind. Löschen Sie eine, öffnen Sie die Shell neu und versuchen Sie es erneut. Der Unterschied zwischen den Variablen ist unter Der Unterschied zwischen ANTHROPIC_AUTH_TOKEN und ANTHROPIC_API_KEY zusammengefasst.

429 — zwei unterschiedliche 429-Fehler

Die Zahl ist dieselbe, aber die Ursachen sind völlig unterschiedlich. Wenn Sie ein Abonnement verwenden, wurde das Limit des Sitzungsfensters erreicht; bis zur Zurücksetzung des Fensters bleibt keine andere Möglichkeit — auch ein Wechsel in einen höheren Tarif hilft in diesem Moment nicht. Wenn Sie einen API-Schlüssel verwenden, handelt es sich um ein Limit für Anfragen pro Sekunde oder den Token-Durchsatz; exponentielle Backoff-Wiederholungen lösen das Problem meist.

Welche Variante vorliegt, erkennen Sie sofort daran, ob ANTHROPIC_BASE_URL gesetzt ist. Wenn es gesetzt ist, verwenden Sie einen Schlüssel und kein Abonnement. Die Struktur des Abonnementlimits und die Möglichkeiten nach dessen Überschreitung werden unter Claude-Code-Preise erläutert.

529 overloaded_error — ein Fehler, der nicht an Ihnen liegt

529 bedeutet, dass der Upstream-Modellserver vorübergehend überlastet ist. Weder der Inhalt der Anfrage noch der Schlüssel oder das Guthaben sind die Ursache; dieser Fehler lässt sich nicht durch Änderungen an den Einstellungen beheben. Es hilft nur ein erneuter Versuch, wobei exponentielles Backoff deutlich höhere Erfolgsraten erzielt als sofortige Wiederholungen.

Über ein Gateway mit automatischem Fallback wird eine Anfrage bei einem 529-Fehler eines Upstreams an einen anderen Pfad weitergeleitet, wodurch die gefühlte Häufigkeit sinkt. Eine ausführliche Zusammenfassung für englischsprachige Leser finden Sie unter Umgang mit 529 overloaded_error.

Nach Erreichen des Abonnementlimits weiterarbeiten

Wenn der 429-Fehler vom Abonnement stammt, können Sie nur diese Sitzung stattdessen auf einen Schlüssel umstellen. Sie müssen das Abonnement nicht kündigen — solange die beiden folgenden Variablen gesetzt sind, wird nur der Schlüssel abgerechnet; nach ihrer Entfernung kehren Sie zum ursprünglichen Zustand zurück.

# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 가리키므로,
# Kunavo가 아직 제공하지 않는 모델이 호출돼 404가 나지 않도록 모델을 고정합니다.
# sonnet 별칭이 부르는 Sonnet 5.5는 Kunavo가 제공하지 않아, 고정하지 않으면
# /model sonnet, opusplan의 실행 단계, sonnet으로 지정한 서브에이전트에서 404가 납니다.
# Opus 5.5는 Claude Code v2.1.280 이상이 필요합니다(이전 버전이면 claude update로 업데이트).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# 백그라운드 작업을 가장 싼 모델로 보내는 한 줄 — 매 세션 효과가 있습니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Die Tarife werden unverändert aus dem Katalog gelesen: Claude Sonnet 5 kostet pro 1 Mio. Token $1.40 / $7.00, Claude Haiku 4.5 kostet $0.70 / $3.50. Die Beträge werden vom Vorauszahlungsguthaben abgezogen, daher entstehen in Monaten ohne Nutzung keine Kosten. Zahlungsmethoden und die Registrierung einer inländischen Karte werden unter Claude API: Preise und Zahlungen erläutert.

Installationsfehler sind ein separates Thema

Probleme bei der Installation werden meist durch die Node.js-Version oder fehlende Berechtigungen für eine globale Installation verursacht und gehören nicht zu den drei oben genannten Fehlern. Prüfen Sie zunächst, ob claude --version ordnungsgemäß ausgegeben wird. Wenn eine Ausgabe erscheint, ist die Installation abgeschlossen; nachfolgende Probleme betreffen Authentifizierung oder Netzwerk. Wer beide Fehlerklassen vermischt, verliert am meisten Zeit.

Häufig gestellte Fragen