Claude Code hataları — 401, 429, 529 ve kurulum hatalarını ayırt etme

Claude Code hataları genel olarak iki türdür ve arama sonuçlarının çoğu yalnızca birini ele alır. Kurulum ve çalıştırma aşamasındaki istemci hataları ile model çağrısı sırasında dönen API hatalarının nedenleri ve çözümleri tamamen farklıdır. Bu yazı ikinci türe — 401, 429 ve 529 — odaklanır. Çünkü abonelikten API anahtarına geçildiği anda ilk karşılaşılan hatalar bunlardır.

Hata dizeleri her ülkede İngilizce görünür. Aşağıda dizeleri özgün hâlleriyle bırakıp yalnızca açıklamaları Türkçeye çeviriyoruz.

Önce nedeni 30 saniyede üçe ayırın

Ayarları değiştirmeden önce uç noktaya doğrudan bir istek gönderin. Bu tek istek, “istemci sorunu / kimlik doğrulama sorunu / sunucu sorunu” ayrımını yapar.

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 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 — anahtar değil, üst bilgi hatalı

Anahtarı birkaç kez yeniden oluşturmanıza rağmen 401 devam ediyorsa değerden çok gönderme biçiminden şüphelenin. Claude Code, ANTHROPIC_AUTH_TOKEN değerini Authorization: Bearer üst bilgisiyle, ANTHROPIC_API_KEY değerini ise x-api-key üst bilgisiyle gönderir. Gateway'ler çoğunlukla ilkini beklediğinden, iki değişkeni ters girerseniz doğru anahtarla bile 401 alırsınız.

İki değişkenin aynı anda kalması da yaygındır. Birini silin, kabuğu yeniden açın ve tekrar deneyin. Değişkenler arasındaki fark ANTHROPIC_AUTH_TOKEN ile ANTHROPIC_API_KEY arasındaki fark bölümünde açıklanır.

429 — birbirinden farklı iki 429 türü

Sayı aynı olsa da neden tamamen farklıdır. Abonelikle kullanıyorsanız oturum penceresi sınırına ulaşmışsınızdır ve pencere sıfırlanana kadar beklemekten başka yol yoktur — o anda üst pakete geçmek de yardımcı olmaz. API anahtarıyla kullanıyorsanız saniye başına istek veya token işlem hacmi sınırıdır; üstel geri çekilmeyle yeniden denemek çoğu durumda sorunu çözer.

Hangisi olduğunu ANTHROPIC_BASE_URL ayarlanmış mı diye kontrol ederek hemen anlayabilirsiniz. Ayarlanmışsa abonelik değil, anahtar kullanıyorsunuz. Abonelik sınırının yapısı ve aşıldığında kullanılabilecek seçenekler Claude Code ücretleri bölümünde açıklanır.

529 overloaded_error — sizin tarafınızdan kaynaklanmayan hata

529, upstream model sunucusunun geçici olarak aşırı yüklendiği anlamına gelir. İstek içeriği, anahtar veya bakiye neden değildir; bu nedenle ayarları düzelterek ortadan kaldıramayacağınız bir hatadır. Tek çözüm yeniden denemektir ve üstel geri çekilme, anında yeniden denemeye göre başarı oranını çok daha fazla artırır.

Otomatik geri dönüşü olan bir gateway kullanırsanız, bir upstream 529 verdiğinde istek başka bir yola aktarılır ve algılanan sıklık azalır. İngilizce konuşan okuyucular için ayrıntılı açıklama 529 overloaded_error ile başa çıkma bölümündedir.

Abonelik sınırına ulaşıldığında çalışmaya devam etme

429 abonelik kaynaklıysa beklemek yerine yalnızca o oturumu anahtara geçirebilirsiniz. Aboneliği iptal etmeniz gerekmez — aşağıdaki iki değişken ayarlı olduğu sürece anahtar üzerinden ücretlendirilirsiniz; değişkenleri silerseniz eski duruma dönersiniz.

# 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

# haiku 별칭도 고정합니다. 고정하지 않으면 Kunavo가 제공하지 않는 모델 ID(v2.1.293부터
# Haiku 5.5)를 호출해 /model haiku와 haiku로 지정한 서브에이전트에서 404가 납니다.
# 같은 줄이 백그라운드 작업도 메인 모델 대신 Haiku로 보냅니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Ücretleri katalogdan doğrudan okuyoruz: Claude Sonnet 5 için 1M token başına $1,40 / $7,00, Claude Haiku 4.5 için $0,70 / $3,50. Tutar ön ödemeli bakiyeden düşülür; bu nedenle çalışmadığınız aylarda ücret oluşmaz. Ödeme yöntemleri ve yerel kart kaydı Claude API fiyatlandırması ve ödemeler bölümünde açıklanır.

Kurulum aşamasındaki hatalar ayrıdır

Kurulumun başarısız olması çoğunlukla Node.js sürümü veya genel kurulum izinlerinden kaynaklanır; yukarıdaki üç hatayla aynı türden değildir. Önce claude --version çıktısının normal olup olmadığını kontrol edin. Çıktı geliyorsa kurulum tamamlanmıştır; sonraki sorun kimlik doğrulama veya ağ tarafındadır. Bu iki türü birbirine karıştırmak en çok zaman kaybettiren yaklaşımdır.

Sık sorulan sorular