OpenRouter 429 Hatası Nasıl Çözülür: Sağlayıcı Hatası mı, Hız Limiti mi?

OpenRouter'da gördüğünüz her 429 hatası, hesabınızın OpenRouter limitine takıldığı anlamına gelmez. Seçtiğiniz üst sağlayıcı da isteği geçici olarak kısıtlıyor olabilir. Önce başarısız olan tek bir isteğin tam kaydını saklayın: HTTP durumu, yanıt başlıkları ve JSON gövdesi hangi limiti çözmeniz gerektiğini gösterir.

Hiçbir Şeyi Değiştirmeden Önce Bir 429 Yanıtını İnceleyin

Kredi satın almadan, anahtarı değiştirmeden veya yeniden deneme eklemeden önce hatanın kaynağını sınıflandırın. OpenRouter'ın türü belirlenmiş alanları ve yanıt başlıkları, üst sağlayıcıdan iletilmiş metinler içerebilen insan tarafından okunabilir hata mesajından daha güvenilir kanıttır.

OpenRouter'ın hata ayıklama referansı, error.code, error.message ve isteğe bağlı error.metadata zarfını tanımlar; buna error_type = "rate_limit_exceeded" da dahildir. Dokümantasyon, başarılı yanıtlarda normalde X-RateLimit-* başlıklarının bulunmadığını da belirtir. Sağlayıcı aşırı yükü ise ayrı olarak provider_overloaded şeklinde tanımlanır ve genellikle 503'e karşılık gelir.

OpenRouter Kaynaklı 429 Hatasını Giderme

OpenRouter düzeyindeki 429, hesabınıza ve model sınıfına tanımlı platform kotasıyla ilgilidir. resmî hız limiti dokümantasyonuna 31 Temmuz 2026 tarihinde göre doğrulandığı üzere, :free ile biten ücretsiz model varyantlarında hem dakika başına hem de günlük limit uygulanır.

Limit politikası, ek hesapların veya anahtarların küresel olarak yönetilen kapasiteyi artırmadığını söylüyor. Bu nedenle geçerli bir anahtarı değiştirmek, platform hız limitini sıfırlamaz.

Kullanımı ve kredi limitlerini görmek için GET /api/v1/key endpoint'ini kullanın:

curl https://openrouter.ai/api/v1/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Platform kaynaklı bir 429 durumunda, hata yanıtındaki sıfırlama başlığını kullanın ve şu adımları sırasıyla uygulayın:

1. Anlık yeniden denemeleri durdurun ve X-RateLimit-Reset zamanına kadar bekleyin.
2. Yalnızca saniye başına istek sayısını değil, eşzamanlı istek sayısını da azaltın. Paralel çalışanlarda oluşan ani yoğunluk, herhangi bir çalışan ilk 429'u görmeden limiti aşabilir.
3. Tüm çalışanların aynı anda uyanıp tekrar denememesi için işleri ortak bir sınırlayıcı arkasında kuyruğa alın.
4. İş yükü ücretsiz model kotasına sığmıyorsa, bu trafiği uygun bir ücretli model varyantına taşıyın.

Negatif bakiye veya anahtar başına kredi limitinin tükenmesi 402 üretmelidir; buna karşılık, hesabı fonlanmış bir kullanıcı da üst sağlayıcıdan 429 alabilir. Ayrı maliyet ve kredi konuları için OpenRouter fiyatlandırma rehberine bakabilirsiniz.

"Provider Returned Error" 429 Hatasını Giderme

Sağlayıcı tarafından dönen 429, OpenRouter'ın üst taraftaki bir çıkarım sağlayıcısına ulaştığı ancak sağlayıcının o anda isteği kabul etmediği anlamına gelir. Türü belirlenmiş hız limiti değerini ve sağlayıcı metadatasını arayın; OpenRouter'a kredi eklemek, o sağlayıcıda kapasite yaratmaz.

Resmî limit referansı, yönlendirmenin hata dönmeden önce alternatif sağlayıcıları zaten denemiş olabileceğini belirtir. Ayrıca denenen her sağlayıcı yeniden deneme ipucu verdiyse Retry-After eklenir. Pratikte şu adımlar işe yarar:

1. Aynı isteği hemen yeniden üretmek yerine Retry-After değerine uyun.
2. Yalnızca tek, yoğun bir rotayı bırakıyorsa aşırı katı sağlayıcı kısıtlamalarını kaldırın.
3. İstek için sağlayıcı fallback seçeneğine izin verildiğini doğrulayın.
4. Görevin tamamlanması, tam olarak aynı modelin kullanılmasından daha önemliyse model fallback yapılandırın.

Fonlanmış bir Zed kullanıcısı moonshotai/kimi-k2:free üzerinde üst kaynaklı bir limite takıldı; anahtarı yeniden oluşturmak sorunu çözmedi. Bir Zed katkıcısı durumu şöyle açıkladı:

“Bu bir Zed hatası değil; OpenRouter, kullandığınız üst sağlayıcının size hız limiti uyguladığını söylüyor.” Kaynak: zed-industries/zed issue #35153

Kısa bir Retry-After süresine uyun. Yalnızca görevi tamamlamak, aynı modeli kullanmaktan önemliyse ücretsiz model fallback kullanın.

Hata Janitor AI, Zed veya SillyTavern'de Görünüyorsa

Ham hata kaydını koruyun, art arda yeniden üretmekten kaçının ve sağlayıcı taraflı hatalarda modeli veya izin verilen rotayı değiştirin. Anahtarı yalnızca istemcideki kayıt sorununu düzeltmek için yeniden girin; bu işlem kapasiteyi sıfırlamaz.

429 Döngüsüne Girmeden Yeniden Deneyin

Yalnızca hız limiti hatalarında yeniden deneyin, deneme sayısını sınırlayın ve önceliği sunucunun belirttiği bekleme süresine verin. Yeniden deneme ipucu yoksa, paralel istemcilerin yeniden aynı anda yoğunluk oluşturmaması için jitter içeren üst sınırlandırılmış üstel backoff kullanın.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryDelayMs(response, attempt) {
  const retryAfter = response.headers.get("retry-after");
  if (retryAfter) {
    const seconds = Number(retryAfter);
    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

    const dateMs = Date.parse(retryAfter);
    if (Number.isFinite(dateMs)) return Math.max(0, dateMs - Date.now());
  }

  const capMs = 30_000;
  const exponentialMs = Math.min(capMs, 1000 * 2 ** attempt);
  return Math.random() * exponentialMs; // Full jitter
}

async function createChatCompletion(body, maxAttempts = 4) {
  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const response = await fetch(
      "https://openrouter.ai/api/v1/chat/completions",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
      },
    );

    const raw = await response.text();
    let payload;
    try {
      payload = raw ? JSON.parse(raw) : null;
    } catch {
      payload = null;
    }
    if (response.ok) return payload;

    const isRateLimit =
      response.status === 429 ||
      payload?.error?.metadata?.error_type === "rate_limit_exceeded";

    if (!isRateLimit || attempt === maxAttempts - 1) {
      const error = new Error(payload?.error?.message || raw || `HTTP ${response.status}`);
      error.status = response.status;
      error.details = payload?.error;
      throw error;
    }

    await sleep(retryDelayMs(response, attempt));
  }
}

Bu işlev akışsız yanıtları ele alır. Çok sayıda bekleyen çalışanın aynı anda yeniden başlamaması için ortak kuyruk veya token-bucket eşzamanlılık kontrolünü bunun dışında uygulayın.

Server-Sent Events, HTTP 200 ile başladıktan sonra durum kodu 429'a dönüşemez. OpenRouter hata referansına göre, daha sonra oluşan hata akış içinde bir error ile ve finish_reason: "error" olarak gelir. Tamamlamayı başarısız kabul edin; yalnızca gömülü tür rate_limit_exceeded ise yeniden deneyin. Uygulamanız kısmi sonuçları açıkça desteklemiyorsa, biriken metni başarılı sonuç olarak döndürmeyin.

Sık Sorulan Sorular

OpenRouter'daki 429 provider returned error ne anlama gelir?

Üst taraftaki bir çıkarım sağlayıcısı, kendi hız veya kapasite limiti nedeniyle isteği reddetmiştir. Bunu error.metadata.error_type ve sağlayıcı metadatasıyla doğrulayın.

Kredim varken neden OpenRouter 429 alıyorum?

Fonlanmış bir hesap da sağlayıcı taraflı 429 alabilir. Yetersiz bakiye veya anahtar başına kredi limiti ise normalde 402 olarak döner.

Yeni bir OpenRouter API key oluşturmak hız limitini sıfırlar mı?

Hayır. Ek anahtarlar küresel olarak yönetilen limitleri artırmaz; anahtarı yalnızca kimlik doğrulama veya istemcide kayıt sorununu çözmek için değiştirin.

OpenRouter'ı yeniden denemeden önce ne kadar beklemeliyim?

Varsa Retry-After değerini kullanın. Platform limiti için X-RateLimit-Reset değerini esas alın; ikisi de yoksa jitter içeren üst sınırlandırılmış üstel backoff ve düşük bir maksimum deneme sayısı kullanın.

OpenRouter HTTP 200 döndürüp yine de 429 nedeniyle başarısız olabilir mi?

Evet; akış çoktan başladıysa bu mümkündür. HTTP durumu 200 olarak kalırken SSE akışı bir hata bildirir ve finish_reason: "error" ile biter. Bunun hız limiti olup olmadığını anlamak için gömülü hata türünü inceleyin.