# Error Handling, Rate Limits, and Retry Strategies

> Source: https://sukruyusufkaya.com/en/learn/claude-ustaligi/error-handling
> Updated: 2026-05-11T13:48:35.448Z
> Category: Claude Ustalığı
> Module: 8. Programmatic Claude with the API
**TLDR:** Classify API errors, apply the right retry strategy, use idempotency keys, design DLQs.

# Hata Sınıfları

| Kod | Anlamı | Retry? |
| --- | --- | --- |
| 400 | Bad Request | Hayır — kodunu düzelt |
| 401 | Unauthorized | Hayır — auth yenile |
| 403 | Forbidden | Hayır — kapsam dışı |
| 404 | Not Found | Hayır |
| 429 | Rate Limited | Evet — exponential backoff |
| 500 | Server Error | Evet — sınırlı |
| 503 | Service Unavailable | Evet |
| 529 | Overloaded | Evet — sınırlı |

```python
import time, random

def with_retry(fn, *, max_attempts=5, base=1.0):
    for attempt in range(max_attempts):
        try:
            return fn()
        except RateLimitError:
            wait = base * 2 ** attempt + random.random()
            time.sleep(wait)
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < max_attempts - 1:
                time.sleep(base * 2 ** attempt + random.random())
            else:
                raise
    raise RuntimeError("retry exhausted")
```

### Idempotency key

Aynı isteği tekrar göndermenin yan etki üretmemesini sağlamak için `Idempotency-Key` HTTP başlığı kullan. Anthropic API bunu destekliyorsa, retry sırasında çift faturalama / çift cevap engelleniyor.

### Retry budget

Her istek başına maksimum 4-5 retry. Üzerine çıkma; cost ve latency çok büyür. Kalanları **dead-letter queue**'ya yolla, insan review'a sun.

### Graceful degradation

API tamamen yanıt vermezse:

- Önbelleklenmiş cevap kullan
- Daha küçük modele düş
- Önceden hazırlanmış 'fallback' cevap dön (UX'i bozmadan)

### Yapılması gereken
- Exponential backoff + jitter
- Idempotency key
- DLQ + alert
- Hata sınıfı bazlı retry kararı
- Latency timeout (60s)

---

### Yapılmaması gereken
- Sonsuz while True
- Sıfır jitter (thundering herd)
- 400/401 retry
- Stateful loglar olmadan retry
- API key yenilemeden 401 retry

**Boşluk doldurma egzersizi (text):**
```text
Retry'lar arası bekleme _____ backoff ile artırılır; thundering herd'i önlemek için _____ eklenir. 400 ve 401 hataları _____ edilmez. Tükenmiş retry'lar _____ kuyruğuna yollanır.
```

> ✋ Kontrol noktası: `q-807-mc1`

> 📝 İlgili quiz: `module-8-final`