Gemini API 429 Hatası (Rate Limit) Nasıl Çözülür?

429 Hatası Ne Anlama Gelir?

HTTP 429 Too Many Requests, bir API'ye belirli bir zaman diliminde izin verilenden daha fazla istek gönderildiğinde dönen standart bir durum kodudur. Gemini API bağlamında bu, hesabınıza tanımlı RPM (dakikalık istek) veya RPD (günlük istek) kotasının aşıldığı anlamına gelir. Sunucu isteğinizi işlemeyi reddeder ve genelde bir süre bekleyip tekrar denemenizi bekler.

Bu hata tek başına bir "arıza" değil — sistemin sizi korumak (ve kaynaklarını adil paylaştırmak) için tasarlanmış bir mekanizmasıdır. Ama uygulamanızda bu hatayı doğrudan kullanıcıya yansıtırsanız, kullanıcı deneyimi ciddi şekilde bozulur.

Neden Oluşur?

En sık karşılaşılan nedenler şunlardır:

• Ücretsiz (free tier) kota limiti aşılmış olabilir. Gemini'nin ücretsiz katmanında dakikalık/günlük istek sayısı oldukça düşüktür.
• Billing aktif değildir. Google Cloud projesinde faturalandırma etkinleştirilmediyse, kota tavanı düşük kalır.
• Birden fazla endpoint aynı API anahtarını paylaşıyordur. Farklı özellikler (örneğin görsel analiz, metin analizi, kalori hesaplama) aynı key'i kullanıyorsa, trafik tek bir kotada birikir.
• Ani trafik artışı. Beklenmedik bir kullanıcı yoğunluğu, normalde yeterli olan bir kotayı hızla tüketebilir.

Çözüm 1: Retry + Exponential Backoff

İlk savunma hattı, isteği hemen tekrar denemek yerine, denemeler arasındaki bekleme süresini her seferinde katlayarak artırmaktır (1sn → 2sn → 4sn → 8sn gibi). Kısa süreli kota patlamalarının büyük kısmı bu şekilde sessizce çözülür, çünkü kota genelde birkaç saniye içinde kendini toparlar.

async function callWithRetry(fn, retries = 3, baseDelayMs = 1000) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const isRateLimit = error?.status === 429;
      const isLastAttempt = attempt === retries;
      if (!isRateLimit || isLastAttempt) throw error;

      const delay = baseDelayMs * Math.pow(2, attempt);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

Burada dikkat edilmesi gereken önemli bir nokta: retry sayısını ve toplam bekleme süresini sınırsız bırakmayın. Özellikle serverless ortamlarda (Vercel, AWS Lambda vb.) fonksiyonunuzun kendi süre limiti var — retry mantığı bu limiti aşarsa, kota sorunu çözülmeden önce fonksiyon zaten zaman aşımına uğrar.

Çözüm 2: Otomatik Fallback (İkinci Sağlayıcı)

Retry, kota gerçekten tükendiğinde işe yaramaz — çünkü sorun geçici değil, kalıcıdır. Bu noktada devreye girmesi gereken şey, birincil sağlayıcı (örneğin Gemini) başarısız olduğunda otomatik olarak ikinci bir sağlayıcıya (örneğin OpenRouter üzerinden farklı bir modele) geçen bir fallback katmanıdır.

try {
  result = await callGemini(prompt);
} catch (error) {
  if (isRateLimitError(error)) {
    result = await callOpenRouterFallback(prompt); // farklı sağlayıcı
  } else {
    throw error;
  }
}

Bu yaklaşımın en büyük avantajı, kullanıcının hiçbir zaman hata görmemesi — sistem kendi kendini iyileştiriyor. Tek bir sağlayıcıya bağımlı kalmamak, üretim ortamındaki en kritik dayanıklılık (resilience) prensiplerinden biridir.

Çözüm 3: Billing ve Kota Artırımı

Retry ve fallback, semptomu yönetir; asıl kök nedeni çözmek için Google Cloud Console veya Google AI Studio üzerinden projenizin billing (faturalandırma) durumunu kontrol edin. Faturalandırma aktifse kota tavanı ciddi şekilde yükselir — çoğu zaman ücretsiz kullanım kotası içinde bile kalırsınız, sadece tavan artar.

Beklenmedik ücretlendirme riskine karşı mutlaka bütçe uyarısı (budget alert) ve kota limiti tanımlayın — bu, hem maliyet kontrolü hem de olası bir API anahtarı sızıntısına karşı bir güvenlik önlemidir.

Serverless Ortamında Dikkat Edilmesi Gerekenler

Vercel gibi serverless platformlarda her fonksiyonun kendi maksimum çalışma süresi (maxDuration) vardır. Retry bütçenizi (toplam bekleme süresini) bu limitin altında tutmazsanız, fonksiyon kota sorunu çözülmeden zaten zaman aşımına uğrar — fallback'e hiç sıra gelmez. Kural olarak: her fonksiyonun retry bütçesi, kendi süre limitinin yaklaşık yarısını geçmemeli; kalan süre fallback çağrısına ve yanıt işlemeye ayrılmalı.

Gerçek Vaka: Prodüksiyonda Yaşadığım Sorun

Aşağıda, bu portföy sitesindeki yapay zeka destekli araçlarda (web sitesi analiz aracı, fotoğraf değerlendirme aracı, kalori hesaplayıcı) yukarıdaki stratejileri gerçekten nasıl uyguladığımı özetliyorum.

Sıkça Sorulan Sorular