⚠️

Claude Code API Hatası Analizi

10 Deneme Sonrası API Error - Kapsamlı Çözüm Rehberi

Olası Sebep

Kontrol Noktası

Çözüm Adımı

📝 Basit Anlatım (Herkes İçin)

Claude Code başında düzgün çalışıyor ancak birkaç işlem (10 deneme) sonrası API hatası veriyor. Bu sorun, Claude Code ile Anthropic sunucuları arasındaki iletişimde bir problem olduğu anlamına geliyor.

Basit açıklama: Telefon görüşmesini düşün. Başta konuşma iyi gidiyor, ancak 10 dakika sonra hattın diğer tarafı konuşmayı kapatıyor veya yanıt vermiyor. Bu olması gereken bir şey değil.

Neden önemli? Bu hata nedeniyle Claude Code ile çalışamıyorsunuz. Her 10 deneme sonrası baştan başlamanız gerekiyor, bu da verimliliği ciddi oranda düşürüyor.

🔧 Teknik Detaylar (Geliştiriciler İçin)

Claude Code 10 deneme yapıyor ve sonra "API Error" döndürüyor. Bu genellikle şu kaynaklardan birinden geliyor:

429 Rate Limit Error: Çok hızlı çok istek gönderiyorsunuz
401 Authentication Error: API anahtarı geçersiz veya süresi dolmuş
529 Overloaded Error: API sunucuları aşırı yüklü
500 API Error: Sunucu tarafında beklenmedik hata
Token Limit: Context window dolmuş veya token limiti aşıldı

🎯 Olası Sebepler (7 Kategori)

1️⃣ API Rate Limiting (Hız Limitleri)

YÜKSEK İhtimal

Claude Code çok hızlı ardışık istekler gönderiyorsa, Anthropic API "429 Rate Limit Error" döndürüyor.

Sebepleri:

Arka planda otomatik çalışan işlemler (auto-refresh, auto-check)
Paralel session'lar çalışıyor
Aggressive retry mekanizması (10 denemeden sonra başarısız oluyor)
Aynı anda birden fazla Claude Code instance açık
Settings'te agresif timeout değerleri

Kontrol Noktaları:

# 1. Açık session sayısını kontrol et
ps aux | grep -i claude

# 2. Ağ trafiğini izle (hangi porttan istek gidiyor?)
netstat -tlnp | grep -i -E 'claude|api'

# 3. API istatistiklerini kontrol et
claude /cost

# 4. Timeout ayarlarını kontrol et
cat ~/.claude/settings.json | grep -i timeout
            

2️⃣ API Key / Authentication Sorunları

YÜKSEK İhtimal

API anahtarınız geçersiz, süresi dolmuş veya kısıtlı erişim izni var olabilir.

Sebepleri:

API anahtarı yanlış kopyalandı (boşluk, karakter kesik)
API anahtarı rotated (yeni anahtar ile değiştirildi)
Token süresi dolmuş (OAuth token'ı refresh gerekiyor)
Kısıtlı model erişimi (belirli modellere erişim yok)
Hesap suspended veya deactivate edilmiş

Kontrol Noktaları:

# 1. Kimlik doğrulamayı sıfırla
claude /logout

# 2. Yeniden giriş yap
claude

# 3. Auth bilgilerini temizle ve sıfırla
rm -rf ~/.config/claude-code/auth.json
claude

# 4. Settings'te API key var mı kontrol et
cat ~/.claude/settings.json | grep -i api
cat .claude/settings.json | grep -i api
            

3️⃣ Network/Connection Sorunları

ORTA İhtimal

İnternet bağlantınız stabil değil veya Proxy/Firewall API isteklerini engelliyor olabilir.

Sebepleri:

Wifi/network bağlantısı kesintili (10. deneme sırasında bağlantı kapanıyor)
Kurumsal Firewall API port'larını engelliyor
Proxy yapılandırması yanlış
DNS resolution sorunları
VPN ile Anthropic API'ye erişim kısıtlanmış

Kontrol Noktaları:

# 1. Network bağlantısını test et
ping -c 5 8.8.8.8

# 2. API endpoint'ine ulaşabildiğini test et
curl -I https://api.anthropic.com

# 3. DNS ayarlarını kontrol et
nslookup api.anthropic.com

# 4. Aktif network adapter'ları listele
ip link show

# 5. Proxy ayarlarını kontrol et
echo $HTTP_PROXY $HTTPS_PROXY
            

4️⃣ Token Limitleri ve Context Window

YÜKSEK İhtimal

İstek çok büyük veya context window dolmuş olabilir. 10. deneme sırasında context window limitine ulaşabilirsiniz.

Sebepleri:

Context window dolmuş (conversation çok uzun)
max_tokens değeri çok yüksek ayarlanmış
İstek boyutu 32 MB'ı aşıyor (API limit)
Large codebase'de çalışılıyor (compacting gerekli)
Sistem prompt çok büyük (CLAUDE.md dosyası çok uzun)

Kontrol Noktaları:

# 1. Context boyutunu kontrol et
claude /compact

# 2. Token kullanımını göster
claude /cost

# 3. CLAUDE.md dosya boyutunu kontrol et
wc -l /var/www/vhosts/tuufi.com/httpdocs/CLAUDE.md
du -h /var/www/vhosts/tuufi.com/httpdocs/CLAUDE.md

# 4. Model'in max context window'unu kontrol et
claude --help | grep -i token
            

5️⃣ Retry Mekanizması Ayarları

ORTA İhtimal

Claude Code'un retry mekanizması 10 denemeden sonra pes ediyor. Bu ayarlar yanlış konfigüre edilmiş olabilir.

Sebepleri:

Retry count = 10 ayarlanmış (max değer)
Retry delay çok kısa (exponential backoff yok)
Retry stratejisi agresif (hemen yeniden başlıyor)
Timeout değeri çok düşük (başarısız olmadan kesiyor)
Connection pool exhausted (bağlantı yönetim sorunu)

Kontrol Noktaları:

# 1. Claude Code settings'ini kontrol et
cat ~/.claude/settings.json
cat .claude/settings.json

# 2. Timeout ayarlarını ara
grep -r "timeout\|retry\|attempt" ~/.claude/ 2>/dev/null

# 3. Environment variables'i kontrol et
env | grep -i -E 'claude|timeout|retry|api'

# 4. Network timeout'unu artır
export CLAUDE_TIMEOUT=60000  # 60 saniye
            

6️⃣ Settings/Configuration Sorunları

ORTA İhtimal

Claude Code settings dosyaları (JSON) yanlış konfigüre olmuş veya bozulmuş olabilir.

Sebepleri:

settings.json dosyası bozulmuş (geçersiz JSON)
Model ayarı yanlış (erişim izni olmayan model)
Permissions çok sıkı ayarlanmış
MCP sunucusu configuration'ı hatalı
Plugin configuration çakışması

Kontrol Noktaları:

# 1. Settings dosyasını valide et
cat ~/.claude/settings.json | jq . > /dev/null && echo "OK" || echo "INVALID JSON"
cat .claude/settings.json | jq . > /dev/null && echo "OK" || echo "INVALID JSON"

# 2. MCP configuration'ını kontrol et
cat .mcp.json 2>/dev/null | jq . > /dev/null && echo "OK" || echo "INVALID"

# 3. Settings dosyalarını sıfırla (BACKUP AL ÖNCE!)
cp ~/.claude/settings.json ~/.claude/settings.json.backup
rm ~/.claude/settings.json

# 4. Claude doctor çalıştır
claude /doctor
            

7️⃣ Anthropic Sunucu Sorunları

DÜŞÜK İhtimal

Anthropic API'nin kendi sunucularında sorun olabilir (nadirdir ancak mümkün).

Sebepleri:

529 Overloaded Error (sunucular aşırı yüklü)
500 Internal Server Error (bug veya konfigürasyon hatası)
Planlı bakım veya downtime
Region-specific sorunlar
API versiyonu deprecated (eski endpoint kullanılıyor)

Kontrol Noktaları:

# 1. API status'unu kontrol et
curl https://status.anthropic.com

# 2. Claude Code version'ını kontrol et
claude --version

# 3. Anthropic docs'taki API change log'unu oku
# https://platform.claude.com/docs

# 4. Problemi report et
claude /bug
            

✅ Adım Adım Çözüm (5 Seviye)

Level 1: Basit Kontroller (2-5 dakika)

Başla buradan! Bu sorunların %40'ı burada çözülüyor.

Adım 1.1: Claude Code'u Yeniden Başlat

# Tüm Claude Code process'lerini kapat
pkill -f claude

# 2-3 saniye bekle
sleep 3

# Yeniden aç
claude
            

Adım 1.2: Açık Session'ları Kapat

# Açık session sayısını kontrol et
ps aux | grep -i claude | grep -v grep

# Eğer 1'den fazla varsa hepsini kapat
pkill -9 -f claude
            

Adım 1.3: Ağ Bağlantısını Test Et

# İnternet bağlantısını test et
ping -c 3 google.com

# Anthropic API'ye erişimi test et
curl -s https://api.anthropic.com > /dev/null && echo "API OK" || echo "API ERR"
            

Adım 1.4: Claude Doctor Çalıştır

claude /doctor

# Çıktıda kırmızı işaretler varsa dikkate al

✅ Sonuç: Eğer bu adımlardan sonra sorun çözülmüşse, problem kapandı. Değilse Level 2'ye geç.

Level 2: Authentication Reset (5-10 dakika)

Bu adımlar %30 oranında sorun çözer.

Adım 2.1: Kimlik Doğrulamayı Sıfırla

# Claude Code'dan çık
claude /logout

# Auth cache'i temizle
rm -rf ~/.config/claude-code/auth.json

# Yeniden giriş yap (fresh login)
claude

# Giriş talimatlarını takip et
            

Adım 2.2: API Key Doğrulaması

# Settings'te API key var mı kontrol et
cat ~/.claude/settings.json 2>/dev/null | grep -i "api_key\|apiKey"

# Eğer API key manuel olarak ayarlanmışsa sil
# (OAuth token daha güvenlidir)
# Ardından logout/login yap
            

✅ Sonuç: Fresh login yapıldıktan sonra yeniden test et. Sorun çözülmüşse bitti. Değilse Level 3'e geç.

Level 3: Configuration Temizliği (10-15 dakika)

Bu adımlar %20 oranında sorun çözer. ⚠️ BACKUP AL!

Adım 3.1: Settings Dosyasını Valide Et

# User settings
cat ~/.claude/settings.json | jq . > /dev/null 2>&1 && echo "✅ User settings OK" || echo "❌ User settings INVALID"

# Project settings
cat .claude/settings.json 2>/dev/null | jq . > /dev/null 2>&1 && echo "✅ Project settings OK" || echo "⚠️ Project settings NOT FOUND or INVALID"

# MCP config
cat .mcp.json 2>/dev/null | jq . > /dev/null 2>&1 && echo "✅ MCP config OK" || echo "⚠️ MCP config NOT FOUND or INVALID"
            

Adım 3.2: Bozuk Settings'i Düzelt

# ÖNCE BACKUP AL!
cp ~/.claude/settings.json ~/.claude/settings.json.backup.$(date +%s)

# Settings dosyasını sil (sıfırlanacak)
rm ~/.claude/settings.json

# Claude Code yeniden açılacak ve varsayılan settings oluşturacak
claude

# İhtiyaç varsa backup'tan restore et
# cp ~/.claude/settings.json.backup.TIMESTAMP ~/.claude/settings.json
            

Adım 3.3: Problematic Plugins'i Devre Dışı Bırak

# .claude/settings.json'ı aç ve kontrol et
cat .claude/settings.json

# Eğer enabledPlugins bölümünde hata varsa:
# Tüm plugin'leri devre dışı bırak (test amacıyla)
            

✅ Sonuç: Fresh settings ile yeniden test et. Sorun çözülmüşse bitti. Değilse Level 4'e geç.

Level 4: Advanced Diagnostics (15-30 dakika)

Bu adımlar %8 oranında sorun çözer. Teknik derinlemesine kontrol.

Adım 4.1: Network Trafiğini İzle

# Claude Code'u başlat (arka planda)
claude &

# Network trafiğini izle (başka terminal'de)
# API request'lerini göreceksin
tcpdump -i any -n 'tcp port 443' | grep -i anthropic

# Veya curl ile test et
curl -v https://api.anthropic.com 2>&1 | head -20
            

Adım 4.2: API Response'ı Ayrıntılı Kontrol Et

# Request'in response code'unu kontrol et
curl -i -X POST https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: YOUR_API_KEY" \
  2>&1 | head -15

# Beklenen: HTTP 200 veya HTTP 400 (not 401/429/500/529)
            

Adım 4.3: Environment Variables'i Kontrol Et

# Claude Code'un kullandığı environment variables
env | grep -i -E 'claude|anthropic|api|timeout|proxy' | sort

# Proxy ayarlanmışsa kontrol et
echo "HTTP_PROXY: $HTTP_PROXY"
echo "HTTPS_PROXY: $HTTPS_PROXY"
echo "NO_PROXY: $NO_PROXY"

# Eğer proxy sorunu varsa:
unset HTTP_PROXY
unset HTTPS_PROXY
unset NO_PROXY
            

Adım 4.4: Large Context Simulation

# Context boyutunu test et
claude /compact

# Token sayısını göster
claude /cost

# Model info'yu göster
claude --help | grep -i context
            

✅ Sonuç: Detaylı diagnostics ile root cause'u belirle. Sorun çözülmüşse bitti. Değilse Level 5'e geç.

Level 5: Nükleer Reset (30-45 dakika)

⚠️ KAPSAMLI RESET - Son çare! %2 oranında sorun çözer.

Adım 5.1: Tüm Claude Code Dosyalarını Sıfırla

# ÇOK ÖNEMLİ: Tüm dosyaları BACKUP AL!
mkdir -p ~/claude-backup-$(date +%Y%m%d-%H%M%S)
cp -r ~/.claude ~/claude-backup-$(date +%Y%m%d-%H%M%S)/
cp -r ~/.config/claude-code ~/claude-backup-$(date +%Y%m%d-%H%M%S)/
cp ~/.claude.json ~/claude-backup-$(date +%Y%m%d-%H%M%S)/ 2>/dev/null

# Tüm Claude Code state'ini sıfırla
rm -rf ~/.claude
rm -rf ~/.config/claude-code
rm ~/.claude.json 2>/dev/null

# Claude Code'u temiz kurulumuyla başlat
claude

# Giriş talimatlarını takip et (fresh setup)
            

Adım 5.2: Claude Code'u Yeniden Kur

# Claude Code'u kaldır
npm uninstall -g @anthropic-ai/claude-code

# Veya native installation'ı kaldır
rm -rf ~/.local/bin/claude

# Yeniden kur (native recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Verify
claude --version
            

Adım 5.3: Sistem Bağlantısını Test Et

# System level network test
curl -v https://api.anthropic.com 2>&1 | grep -E "HTTP|Connected"

# DNS test
nslookup api.anthropic.com

# Firewall test
sudo iptables -L -n 2>/dev/null | grep -i 443

# Proxy test (eğer kurumsal ağda)
curl -v -x [PROXY]:PORT https://api.anthropic.com
            

❌ Hala sorun yaşıyorsan: Anthropic Support'a başvur. /bug komutu ile hata bildir. Backup'larından restore et.

📊 Hızlı Tanı Tablosu

Hata Mesajı	Muhtemel Sebep	İlk Çözüm	Detaylı Çözüm
`429 Rate Limit`	Çok hızlı istek	Bekleme	Level 1: Claude'u restart + Açık session'ları kapat
`401 Unauthorized`	API key geçersiz	/logout, /relogin	Level 2: Auth reset
`500 Server Error`	Anthropic sunucu hatası	Bir kaç dakika bekle	Level 4: İnternet connection kontrol
`529 Overloaded`	API sunucuları aşırı yüklü	Daha sonra yeniden dene	Peak hours'dan kaçın (9-17 UTC)
`Invalid JSON`	Settings dosyası bozuk	Settings dosyasını sil	Level 3: Configuration temizliği
`Connection Timeout`	Network sorunları	VPN/Proxy kontrol	Level 4: Network diagnostics
`After 10 attempts`	Retry limit aşıldı	Context window kontrol	Level 4: /compact yap, token boyutunu azalt

💡 Advanced Tips

🔧 Settings Optimization

{
  "model": "sonnet",
  "timeout": 60000,
  "retryAttempts": 5,
  "retryDelay": 2000,
  "maxContextSize": 100000,
  "enableCompactMode": true,
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}
            

⚠️ Önemli Seçenekler:

timeout: 60 saniye çok iyi, timeout: 120000 yapabilirsin
retryAttempts: 5 iyi, 10'dan fazla yapma
retryDelay: 2 saniye, exponential backoff için artır
maxContextSize: Büyük codebase'de 150000 yap
enableCompactMode: Uzun conversation'larda true yap

⚡ Environment Variables

# ~/.bashrc veya ~/.zshrc'ye ekle
export CLAUDE_TIMEOUT=120000
export CLAUDE_MAX_RETRIES=5
export CLAUDE_RETRY_DELAY=2000
export CLAUDE_LOG_LEVEL=debug
export ANTHROPIC_API_TIMEOUT=120
export ANTHROPIC_CONNECT_TIMEOUT=30

# Eğer proxy varsa:
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com
            

🚀 Performance Optimization

Haftalık /compact yap (context temizliği)
Büyük codebase'de @ ile file reference kullan
Uzun conversation'ları session'lara bölümle
Off-peak hours'da büyük işler yap (01:00-09:00 UTC)
CLAUDE.md dosyasını 5000 satırdan az tut
Paralel session açma (bir seferde bir session)

📞 Anthropic Support İletişim

Yukarıdaki adımları denedikten sonra hala sorun varsa:

Claude Code'da claude /bug komutunu çalıştır
Aşağıdaki bilgileri ekle:
# Hata göründüğü zaman: - Session ID - Request ID (error response'dan) - Deneme sayısı (1-10 arasında hangisinde oluyor?) - Settings dosyası (sensitif bilgi kaldır) - Network ortamı (corporate/home/mobile) - OS ve Claude Code version
Email: support@anthropic.com
Rapor: https://github.com/anthropics/claude-code/issues

📋 Hızlı Kontrol Listesi

Bugün Yapılacaklar

Claude Code'u restart et
/doctor çalıştır
/logout ve /login yap
Network bağlantısını test et
Settings dosyasını valide et
Açık session'ları kapat

Bu Hafta Yapılacaklar

CLAUDE.md dosyasını optimize et
Context boyutunu azalt (/compact)
Settings.json'ı ayarla (timeout, retry)
Plugins'i gözden geçir
MCP configuration'ını kontrol et
Network/Proxy ayarlarını düzelt