Claude API 429 rate_limit_error — nedenleri ve işe yarayan çözüm

Claude API'deki 429, Anthropic'in dakika başına limitlerinden birini — istek, giriş token'ı veya çıkış token'ı — aştığınız anlamına gelir. Çözüm nadiren "daha uzun beklemek"tir: retry-after'a uymak, jitter içeren geri çekilme eklemek ve ani yükleri yumuşatmaktır. Eksiksiz yol haritası burada.

Hata

yanıt (HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

Nedenler ve çözümler özeti

Neden	Çözüm
Dakika başına istek (RPM) limiti aşıldı	İstekleri istemci tarafında kuyruğa alın; yeniden denemeden önce retry-after başlığına uyun.
Dakika başına giriş token'ı (ITPM) aşıldı — büyük istemler, az istek	Alınan bağlamı kısaltın; desteklenen planlarda önbelleğe alınan token'ların size karşı sayılmasını durdurmak için istem önbelleğe almayı etkinleştirin.
Dakika başına çıkış token'ı (OTPM) aşıldı	max_tokens değerini gerçekçi ayarlayın — uzun üretimlerde ilk sınır çoğu zaman OTPM'dir.
Ani trafik (cron her şeyi :00'da çalıştırıyor)	Zamanlamalara jitter ekleyin; toplu işleri dakika geneline yayın.

Yeniden denemeden önce yanıtı okuyun

Anthropic, beklenecek saniye sayısını içeren bir retry-after başlığı döndürür ve hata mesajı hangi limiti aştığınızı belirtir. Yanıtı okumadan anında yeniden denemek, tek bir 429'un 429 fırtınasına dönüşmesine neden olur.

Jitter içeren üstel geri çekilme ekleyin

Yalnızca yeniden denenebilir durumları (429, 500, 529) yeniden deneyin; kimlik doğrulama veya doğrulama hatalarını asla denemeyin. Bu kod parçası doğrudan Anthropic'e veya OpenAI uyumlu herhangi bir uç noktaya değişiklik yapılmadan uygulanır:

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Yalnızca istekleri değil, token'ları azaltın

Mesaj token limitlerinden söz ediyorsa yalnızca geri çekilme sizi kurtarmaz. Alınan parçaları azaltın, max_tokens değerini sınırlayın ve istem önbelleğe almayı etkinleştirin — giriş hızının %10'unda büyük, sabit bir sistem istemi de ITPM baskısını azaltır.

Kunavo üzerinden çağrı yapıyorsanız

Claude'u Kunavo üzerinden çağırmak hız limitlerini sihirli biçimde kaldırmaz, ancak hata ekonomisini değiştirir: başarısız istekler (429'lar dahil) hiçbir zaman faturalandırılmaz ve anahtar başına kullanım panosu hangi anahtarın ve modelin ani yük oluşturduğunu tam olarak gösterir; böylece yükü yumuşatabilirsiniz. Yukarıdaki aynı geri çekilme kodu olduğu gibi çalışır — yalnızca base_url farklıdır. Hız limitleri fiyat değil, verim sınırıdır — bir Claude çağrısının 1M token başına gerçek maliyeti ve Anthropic'in resmi listesiyle karşılaştırması için şu adrese bakın: Anthropic Claude API fiyat listesi.

Sık sorulan sorular

Anthropic katmanımı yükseltmek 429'ları ortadan kaldırır mı?

Daha yüksek katmanlar dakika başına sınırları artırır; bu nedenle 429'lar azalır, ancak her sabit sınıra ani yükle ulaşılabilir. Üretim kodunda katmandan bağımsız olarak geri çekilme gerekir.

429'u hemen yeniden denemeli miyim?

Hayır — retry-after başlığına uyun (başlık yoksa jitter içeren üstel geri çekilme kullanın). Anında yeniden denemeler hız sınırlı pencereyi uzatabilir ve daha uzun bir kilitlenmeye yol açabilir.

Başarısız 429 istekleri ücretli midir?

Anthropic reddedilen istekler için ücret almaz; Kunavo da almaz — başarısız istekler hiçbir zaman faturalandırılmaz. 429'un maliyeti para değil gecikmedir.

İlgili kılavuzlar

Hata anlamlarına ilişkin daha fazla bilgi hata referansı bölümünde; anahtar almak kayıt ve kimlik doğrulama kılavuzu üzerinden bir dakika sürer.