Claude API 500 api_error ve 502 Bad Gateway — gerçekten kurtaran bir yeniden deneme politikası

500 ve 502 bir arızaya işaret eder, limite değil. Bu nedenle, 429'un aksine — kendi hız limitinizdir — ve sağlayıcının kapasitesinin dolu olduğunu gösteren 529'un aksine, bu hata sınıfı neredeyse hemen yeniden denenmeye değerdir. Üçünden yanlış olanı yeniden denemek, küçük bir olayı kendi olayınıza dönüştürür.

Hata

iki biçim, aynı çözüm

// Straight from the model provider (HTTP 500)
{
  "type": "error",
  "error": { "type": "api_error", "message": "Internal server error" }
}

// From a gateway or proxy in between (HTTP 502)
{
  "error": {
    "message": "Failed to reach upstream provider",
    "type": "upstream_error",
    "code": "upstream_error",
    "param": null
  }
}

Nedenler ve çözümler özeti

Neden	Çözüm
Geçici sağlayıcı tarafı arızası	Üstel geri çekilme ve jitter ile yeniden deneyin; yaklaşık 5 denemeyle sınırlayın.
Bağlantı kabul edildi, ardından hiç yanıt gelmedi	Hata değil, takılma. İlk bayta kadar geçen süreyi toplam süreden ayrı şekilde sınırlandırın.
Kendi 502 hatasını döndüren bir aracı	Modelle ilgisi yoktur. Gövdenin sağlayıcının biçiminde mi yoksa bir proxy'nin biçiminde mi olduğunu kontrol edin.
Gerçek bir olay sırasında körü körüne yeniden denemek	Denemeleri sınırlayın ve geri çekilin — aksi takdirde yeniden denemeleriniz kesintinin bir parçası olur.

Bir çözüm seçmeden önce 500'ü 529 ve 429'dan ayırın

429, aştığınız bir hız limitidir — yavaşlayın. 529, sağlayıcının kapasitesine ulaştığını gösterir — çok daha fazla ve daha uzun süre geri çekilin. 500/502, genellikle kısa süren ve çoğu zaman tek bir isteğe özgü olan bir arızadır. Yalnızca üçüncüsü hızlıca yeniden denenmeye değerdir; üçünü de aynı şekilde ele almak, yeniden deneme döngülerinin olayları kötüleştirmesinin nedenidir.

5xx'i yeniden deneyin, 4xx'i asla yeniden denemeyin

Jitter içeren üstel geri çekilme ve en fazla beş deneme. Aynı yardımcı her sağlayıcı için çalışır — 400 veya 422, bir sonraki denemede de aynı şekilde başarısız olur; dolayısıyla yeniden denemek yalnızca aynı hataya ulaşmak için gecikme harcar.

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)

İlk bayta kadar geçen süreyi toplam süreden ayrı sınırlayın

Tüm istek için tek bir zaman aşımı, uzun bir üretimi kopmuş bir bağlantıdan ayırt edemez. İlk bayt için kısa, geri kalanı için cömert bir son tarih belirleyin; böylece takılma hızlıca başarısız olurken gerçekten yavaş bir yanıt olduğu gibi bırakılır.

Her deneme için durumu ve gecikmeyi günlüğe kaydedin

Her denemeye ait kayıtlar olmadan, bir sağlayıcı olayı ile kendi zaman aşımınız sonradan aynı görünür. Durum kodu, gecikme ve deneme numarası, ertesi sabah bunları ayırt etmek için yeterlidir.

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

Eylül 2026 itibarıyla Kunavo'daki her Claude modeli tek bir üst kanal üzerinden sunulmaktadır; bu nedenle bu kanaldan gelen bir 5xx istek içinde yeniden denenmez: “Upstream provider error” mesajını taşıyan bir 502 olarak size ulaşır (/v1/messages üzerinde api_error türünde) ve istek sıfır maliyetle kaydedilir. Kunavo'nun istek içi yeniden denemesi yalnızca ikinci bir kanal yapılandırılmış bir model için çalışır: zaman aşımı, 5xx, 429 veya Kunavo'nun kendi üst akış anahtarının reddedilmesi, size ulaşmadan önce bu kanalda yeniden denenir; bu işlem /v1/messages, /v1/responses ve /v1/chat/completions üzerindeki Claude modelleri için geçerlidir. Bir akış, ilk içeriği gelene kadar bekletilir; bu nedenle henüz başlamamış bir akış içindeki hata da yeniden denenir. İçerik akışı başladıktan sonra, akışın ortasındaki bir hata sizin tarafınızdan ele alınmalıdır. Her iki durumda da bu sayfadaki yeniden deneme politikasını kendi tarafınızda uygulayın. Bu davranışın arkasındaki yönlendirme AI gateway kılavuzumuzda açıklanmaktadır.

Sık sorulan sorular

500 döndüren bir istek için ücretlendirilir miyim?

Kunavo'da hayır — başarısız istekler sıfır maliyetle kaydedilir. Bir sağlayıcıyla doğrudan yapılan faturalandırma değişiklik gösterebilir, ancak 5xx genellikle ücretlendirilmez.

500'ü yeniden denemek iki tamamlanmış sonuç üretebilir mi?

Evet. Bir istek, model üretimi tamamladıktan sonra başarısız olabilir. Çalışmanın yan etkileri varsa, yeniden denemeleri eklemeden önce kendi katmanınızda idempotent olmasını sağlayın.

500, 502 ve 529 arasındaki tek satırlık fark nedir?

500, sağlayıcının arızalanmasıdır; 502, önündeki bir şeyin sağlayıcıya ulaşamamasıdır; 529 ise sağlayıcının kapasitesinin dolu olmasıdır — ilk ikisini kısa süre içinde, üçüncüsünü ise çok daha sonra yeniden deneyin.

İ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.