Erreurs de Claude Code — distinguer 401, 429, 529 et les erreurs d’installation

Les erreurs de Claude Code se divisent principalement en deux catégories, et la plupart des résultats de recherche n’en traitent qu’une seule. Les erreurs du client lors de l’installation ou de l’exécution et les erreurs d’API renvoyées lors de l’appel au modèle ont des causes et des solutions complètement différentes. Cet article se concentre sur les secondes — 401, 429 et 529 — car ce sont les erreurs rencontrées en premier lors du passage d’un abonnement à une clé d’API.

Les chaînes d’erreur apparaissent en anglais quel que soit le pays. Ci-dessous, les chaînes sont conservées telles quelles et seules les explications sont en coréen.

Commencez par répartir la cause en trois catégories en 30 secondes

Avant de modifier les paramètres, envoyez directement une requête au point de terminaison. Cette seule requête permet de distinguer « problème client / problème d’authentification / problème serveur ».

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 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 — l’en-tête est incorrect, pas la clé

Si l’erreur 401 persiste malgré plusieurs nouvelles clés, soupçonnez non pas la valeur, mais le mode d’envoi. Claude Code envoie ANTHROPIC_AUTH_TOKEN dans l’en-tête Authorization: Bearer, et ANTHROPIC_API_KEY dans l’en-tête x-api-key. Les passerelles attendent généralement le premier format ; si vous inversez les deux variables, vous obtenez une erreur 401 même avec une clé valide.

Il est également courant que les deux variables soient encore définies. Supprimez-en une, ouvrez un nouveau shell, puis réessayez. La différence entre les variables est expliquée dans Différence entre ANTHROPIC_AUTH_TOKEN et ANTHROPIC_API_KEY.

429 — deux erreurs 429 différentes

Le nombre est identique, mais la cause est totalement différente. Si vous utilisez un abonnement, vous avez atteint la limite de la fenêtre de session et devez attendre sa réinitialisation — passer à un forfait supérieur n’aidera pas à ce moment-là. Si vous utilisez une clé d’API, il s’agit d’une limite du nombre de requêtes par seconde ou du débit de tokens ; les nouvelles tentatives avec backoff exponentiel résolvent généralement le problème.

Vous pouvez les distinguer immédiatement en vérifiant si ANTHROPIC_BASE_URL est défini. S’il l’est, vous utilisez une clé et non un abonnement. La structure des limites d’abonnement et les options après dépassement sont présentées dans Tarifs de Claude Code.

529 overloaded_error — une erreur qui ne vient pas de vous

529 signifie que le serveur de modèles amont est temporairement surchargé. Ni le contenu de la requête, ni la clé, ni le solde n’en sont la cause ; ce n’est donc pas une erreur que vous pouvez faire disparaître en modifiant vos paramètres. Il faut réessayer, et le backoff exponentiel offre un bien meilleur taux de réussite qu’une nouvelle tentative immédiate.

Avec une passerelle dotée d’un basculement automatique, lorsqu’un amont renvoie 529, la requête passe par une autre route, ce qui réduit la fréquence ressentie. Une présentation détaillée destinée aux lecteurs anglophones figure dans Réagir à 529 overloaded_error.

Continuer à travailler après avoir atteint la limite d’un abonnement

Si le 429 vient de l’abonnement, vous pouvez faire basculer uniquement cette session vers une clé au lieu d’attendre. Il n’est pas nécessaire de résilier l’abonnement — tant que les deux variables ci-dessous sont définies, la clé est utilisée pour la facturation ; supprimez-les pour revenir au fonctionnement initial.

# 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

Les tarifs sont lus directement dans le catalogue : Claude Sonnet 5 coûte $1.40 / $7.00 par million de tokens, et Claude Haiku 4.5 coûte $0.70 / $3.50. Le montant est déduit du solde prépayé ; aucun coût n’est donc généré pendant les mois sans utilisation. Les moyens de paiement et l’enregistrement d’une carte nationale sont expliqués dans Tarifs et paiement de l’API Claude.

Les erreurs d’installation sont distinctes

Les problèmes d’installation sont généralement causés par la version de Node.js ou les droits d’installation globale et appartiennent à une catégorie différente des trois erreurs ci-dessus. Vérifiez d’abord que claude --version s’affiche normalement. Si c’est le cas, l’installation est terminée et le problème ultérieur concerne l’authentification ou le réseau. Mélanger ces deux catégories est la façon la plus sûre de perdre du temps.

Questions fréquentes