AI API Rate Limiting: Nasıl Çalışır ve Nasıl Yönetilir

Bir AI API'sinden gelen 429 yanıtı dört farklı anlama gelebilir: dakika başına çok fazla istek, dakika başına çok fazla token, çok fazla eşzamanlı bağlantı veya tükenmiş hesap bakiyesi. Dördü de aynı durum kodunu döndürür, bu nedenle çözüm daha fazla deneme yapmaya değil, hangi sınıra çarptığınızı teşhis etmeye bağlıdır. Bu kılavuz, hata modlarını inceler, mevcut limitler hakkında hangi kanıtların mevcut olup hangilerinin olmadığını gösterir ve üretim ortamında işe yarayan bir yeniden deneme ve yedekleme (fallback) modeli sunar.

Önemli Çıkarımlar

• Bir 429 hatası; istek tavanı, token bütçesi, eşzamanlılık sınırı veya tükenmiş hesap bakiyesi anlamına gelebilir. Her birinin farklı bir çözümü vardır ve genel yeniden denemeler bu dört sorundan sadece birini çözer.
• Hız sınırı başlıklarını (rate-limit headers) sadece hatalardan sonra değil, başarılı yanıtlar aldığınızda da okuyun ve sınıra yaklaşmadan önce trafiği kısın.
• İstemci tarafındaki token sayımı bir tahmindir, garanti değildir. Kitaplığınız ile sağlayıcının gerçek sayımı arasındaki tokenizer uyumsuzlukları, güvenlik marjınızı düşündüğünüzden daha dar hale getirebilir.
• Model ve katman başına kesin RPM/TPM tavanları, bu makale için mevcut olan kanıtlarda yayınlanmamıştır. Başka yerlerde gördüğünüz sayıları sabit birer sabit olarak değil, kendi hesap panelinizden doğrulamanız gereken veriler olarak kabul edin.
• Dayanıklı yeniden denemeler; üstel geri çekilme (exponential backoff), jitter (rastgele gecikme), maksimum yeniden deneme sayısı gerektirir ve retry-after başlığına saygı duymalıdır. İdempotent olmayan (tekrarlandığında yan etki yaratan) işlemleri asla körü körüne yeniden denemeyin.

AI API Hız Sınırlamasını Anlamak: Dört Hata Modu

İstek limitleri

Çoğu sağlayıcı dakika başına istek (RPM) sayısını hesaplar. Bunu aşarsanız, genellikle boş bir gövde ile anında 429 alırsınız. Sonuçlar arasında hızla gezinen bir kullanıcı veya kısıtlama olmadan çalışan bir cron işi, yaygın tetikleyicilerdir.

Token limitleri

Ekiplerin en çok hafife aldığı tuzak budur. Sağlayıcılar genellikle dakika başına token (TPM) sınırını RPM'den ayrı olarak uygular, bu nedenle istek tavanınızın oldukça altında olsanız bile 429 hatası alabilirsiniz. Geniş bağlamlı modeller bunu daha da kötüleştirir: TokenLab canlı fiyatlandırma kanıtlarına göre (2026-07-07 tarihinde gözlemlenmiştir), Claude Opus 4.8 ve GPT-5.5, 1.000.000+ token bağlamı destekler. Büyük bir belgeyi, tam bir kod tabanını veya uzun bir sohbet geçmişini bu pencereye yükleyen bir çağrı, "tek" bir istek olmasına rağmen dakika başına token bütçenizin büyük bir kısmını tüketebilir. Bu, ölçülen çağrı başına token sayısına değil, bağlam penceresi boyutuna dayalı bir kapasite planlama riskidir, bu nedenle sabit bir rakam varsaymak yerine gerçek kullanımı kendi günlüklerinizle doğrulayın.

Eşzamanlılık limitleri

Sağlayıcılar, siz aynı anda elli akış açana kadar ortalama dakika başına hacminizi tolere edebilir. Eşzamanlılık limitleri, aynı anda devam eden istekleri veya bağlantıları sınırlar. Akış (streaming) yanıtları bağlantıları daha uzun süre açık tutar, bu da eşzamanlılık yuvalarını kısa, tek seferlik çağrılardan daha hızlı tüketir. Claude Sonnet 5 veya Kimi K2.7 Code üzerine inşa edilmiş kodlama ajanları ve Gemini 3.5 Flash'tan yayın yapan ses arayüzleri, aynı anda birçok uzun ömürlü bağlantıyı açık tuttukları için yaygın tetikleyicilerdir.

Kota veya bakiye tükenmesi

Bu, panelinizde bir hız sınırı ile aynı görünür: çağrılar çalışmayı durdurur. Ancak çözüm farklıdır. Hesabınız ön ödemeli kredileri tüketirse veya katı bir günlük harcama sınırına ulaşırsa, API bir hız sınırına benzeyen bir hata döndürür. Burada geri çekilme (backoff) işe yaramaz. Bakiyeyi yüklemeniz veya harcama eşiğini yükseltmeniz gerekir.

Kaynak Anlık Görüntüsü

Veri noktası	Kaynak	Gözlem tarihi
Model bağlam pencereleri ve token başına fiyatlandırma	TokenLab canlı model/fiyatlandırma kanıtı	2026-07-07
Model SSOT isimlendirmesi (Claude Sonnet 5, GPT-5.5, Gemini 3.5 Flash, vb.)	TokenLab model SSOT	2026-07-07, son kullanma 2026-07-14
Resmi sağlayıcı RPM/TPM katman limitleri	Bu kanıt setinde mevcut değil	Doğrulanmadı, sağlayıcı hesap panelini kontrol edin
TokenLab ağ geçidi başlık normalleştirme davranışı	Bu kanıt setinde mevcut değil	Tek bir başlık şemasına güvenmeden önce TokenLab API dokümanlarını doğrulayın

Mevcut Model Bağlam Pencereleri ve Fiyatlandırma (TokenLab Canlı Kanıtı)

Bu rakamlar doğrudan TokenLab canlı fiyatlandırma anlık görüntüsünden gelmektedir. Bunlar RPM veya TPM limitleri değildir; büyük bağlamlı bir modeldeki tek bir çağrının neden token bütçesini orantısız bir şekilde tüketebileceğini gösterirler.

Model	Sağlayıcı	Bağlam penceresi	Girdi $/MTok	Çıktı $/MTok	Kaynak	Gözlem
Claude Sonnet 5	Anthropic	1.000.000	$2.00	$10.00	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
Claude Opus 4.8	Anthropic	1.000.000	$5.00	$25.00	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
Claude Fable 5	Anthropic	1.000.000	$10.00	$50.00	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
GPT-5.5	OpenAI	1.050.000	$5.00	$30.00	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
GPT-5.5 Batch/Flex	OpenAI	1.050.000	$2.50	$15.00	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
Gemini 3.5 Flash	Google	1.048.576	$1.50	$9.00	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
GLM-5.2	Z.ai	1.048.576	$0.93	$3.00	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
Kimi K2.7 Code	Moonshot AI	262.144	$0.74	$3.50	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
DeepSeek V4 Pro	DeepSeek	1.048.576	$0.44	$0.87	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
DeepSeek V4 Flash	DeepSeek	1.048.576	$0.09	$0.18	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
Qwen3.7 Plus	Alibaba	1.000.000	$0.32	$1.28	TokenLab canlı fiyatlandırma kanıtı	2026-07-07
MiniMax M3	MiniMax	1.048.576	$0.30	$1.20	TokenLab canlı fiyatlandırma kanıtı	2026-07-07

Model SSOT notu: bu isimler 2026-07-07 tarihinde gözlemlenen ve 2026-07-14 tarihinde sona eren TokenLab model SSOT'unu yansıtır. İsimlendirme ve kullanılabilirlik sık sık değişir. Üretim koduna bir model dizisi kodlamadan önce, TokenLab model dizininde veya model liderlik tablosunda hala çözümlendiğini doğrulayın.

Yeniden Deneme Mantığını Sıfırdan Yazmadan Hız Sınırı Hatalarını Düzeltin

Yukarıdaki her şey teşhistir. İyileştirme çalışması, hangi modele geçileceğine karar vermek, kullanıcı başına eşzamanlılığı izlemek ve hangi model ailelerinin sağlıklı olduğuna dair canlı bir resim tutmak, tam olarak TokenLab'in yönlendirme katmanının üstlenmek üzere tasarlandığı şeydir. Beş sağlayıcı arasında bir yedekleme matrisi oluşturmak yerine, istekleri TokenLab'e yönlendirirsiniz ve ağ geçidinin mevcut model kataloğu arasından kullanılabilirliğe ve yedekleme kurallarınıza göre seçim yapmasına izin verirsiniz.

Dürüst bir uyarı: TokenLab birden fazla yukarı akış (upstream) sağlayıcısının önünde durur ve her biri kendi başlık setini, hata formatını ve yeniden deneme semantiğini döndürür. Ağ geçidinin her hız sınırı başlığını tam olarak tek bir tutarlı şemaya normalleştirip normalleştirmediği veya bazı yukarı akış başlıklarını değiştirmeden geçirip geçirmediği, bu makale için mevcut olan kanıtlarda doğrulanmamıştır. Her modelde tek bir birleşik şema varsayan bir ayrıştırma mantığı yazmadan önce TokenLab'in API dokümanlarındaki mevcut başlık davranışını doğrulayın. Başlık ayrıştırıcınızı, var olduğunu varsaymak yerine her alanın varlığını kontrol ederek savunmacı bir şekilde oluşturun.

Hız Sınırı Başlıklarını Okuma

Sağlayıcılar hız sınırı bilgilerini yanıt başlıklarında döndürür, ancak tam isimler sağlayıcıya göre değişir. Yaygın bir model şöyledir:

x-ratelimit-limit-requests: 500
x-ratelimit-remaining-requests: 499
x-ratelimit-reset-requests: 12s
retry-after: 0

Bunları sadece bir 429 hatasından sonra değil, başarılı yanıtlar aldığınızda da okuyun. Kalan bütçenin sürekli bir sayımını tutun ve bir güvenlik eşiğinin altına düştüğünüzde yavaşlayın; bu genellikle %10-20'lik bir boşluktur, ancak doğru sayı trafik yoğunluğunuza bağlıdır ve bu kanıt setinin sizin için belirleyebileceği bir şey değildir.

Açık Hata Yönetimi ile Yeniden Deneme Mantığı

Bir yeniden deneme yardımcısı, 429 durumundan fazlasını yönetmelidir. Geçici hataları (429, 503, zaman aşımları) yeniden denemede asla başarılı olmayacak istemci hatalarından (429 dışındaki 4xx) ayırmalı ve mevcut olduğunda retry-after başlığına saygı duymalıdır.

async function callWithRetry(fn, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const status = err.status;

      // 429 dışındaki istemci hataları yeniden denemede başarılı olmaz
      if (status && status >= 400 && status < 500 && status !== 429) {
        throw err;
      }

      // Hata türüne bakılmaksızın maksimum denemeden sonra pes et
      if (attempt === maxRetries) throw err;

      // 429: mevcutsa retry-after'a uyun, aksi takdirde jitter ile geri çekilin
      if (status === 429) {
        const retryAfter = parseRetryAfterHeader(err);
        const delay = retryAfter
          ? retryAfter * 1000
          : Math.pow(2, attempt) * 1000 + Math.random() * 1000;
        await sleep(delay);
        continue;
      }

      // 503 veya ağ zaman aşımı: geri çekilin ve yeniden deneyin, gözlemlenebilirlik için günlüğe kaydedin
      if (status === 503 || err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET') {
        await sleep(Math.pow(2, attempt) * 1000 + Math.random() * 1000);
        continue;
      }

      // Bilinmeyen 5xx: geri çekilme ile yeniden dene, denemeleri sıkı tut
      if (status && status >= 500) {
        await sleep(Math.pow(2, attempt) * 1000 + Math.random() * 1000);
        continue;
      }

      throw err;
    }
  }
}

Ödeme tahsilatı veya yan etkileri olan bir yazma işlemi gibi idempotent olmayan işlemleri asla saf bir yeniden deneme döngüsüne sarmayın. Bu çağrıları yeniden denemeden önce idempotency (eşdeğerlik) durumunu onaylayın veya bir idempotency anahtarı kullanın.

Token Tahmin Doğruluğu: Yerel Sayımlar Neden Sağlayıcı Sayımlarından Sapıyor?

İstemci tarafındaki token sayma kitaplıkları, belirli bir modelin aslında kullandığı tokenizer'ı yaklaşık olarak hesaplar. tiktoken, OpenAI'nin ailesiyle yakından eşleşir ancak Anthropic, Google veya açık ağırlıklı tokenizer'larla tam olarak eşleşeceği garanti edilmez. Farklılıklar özel tokenlar, çok baytlı karakterler ve sistem istemi biçimlendirmesi etrafında ortaya çıkar ve uzun konuşmalarda birikir.

Sapmayı azaltmak için pratik adımlar:

• Yanıt gövdesinde döndürülen gerçek token kullanımını okuyun (çoğu sağlayıcı istem ve tamamlama token sayılarını içerir) ve yerel tahmincinizi zaman içinde kalibre etmek için bunu kullanın.
• Katı bir sınır değil, bir güvenlik marjı tutun. Sağlayıcınızın TPM sınırı tahmini kullanımınıza yakınsa, isteği tam sınırda göndermek yerine geciktirin veya bölün.
• İstemleriniz büyükse veya çağrılar arasında tekrarlanıyorsa, tokenizasyon davranışı ve istem bölme stratejileri hakkındaki TokenLab kapsamına bakın; böylece bir sınıra çarpmadan önce istek başına token miktarını azaltmanın somut yollarını görebilirsiniz. Çağrı başına token miktarını azaltmak, genellikle daha yüksek bir katman için pazarlık yapmaktan daha ucuz bir çözümdür.

Trafik Şekillendirme ve Model Yedekleme

Jitter ile üstel geri çekilme. Her yeniden denemeden sonra bekleme süresini ikiye katlayın ve eşzamanlı istemcilerin kilitli bir şekilde yeniden denememesi için rastgele jitter ekleyin.

Kullanıcı veya görev başına trafik şekillendirme. Kullanıcı başına eşzamanlı çağrıları sınırlayın (örneğin, 3 eşzamanlı, saniyede 5 istek patlaması), böylece bir ağır kullanıcı tüm hesap genelindeki limitinizi tüketip diğer herkesin performansını düşüremez.

Göndermeden önce token bütçesi tahmini. Tokenları istemci tarafında sayın ve bir istek sizi takip edilen TPM bütçenizin üzerine çıkaracaksa, gönderip umut etmek yerine geciktirin veya bölün.

Bir güvenlik ağı olarak model yedekleme. Birincil model bir 429 döndürdüğünde, ayrı limitleri ve benzer yetenekleri olan bir alternatife yönlendirin. Bir kodlama görevi, Claude Sonnet 5'ten DeepSeek V4 Pro veya Kimi K2.7 Code'a devredilebilir. Yüksek hacimli, düşük maliyetli bir iş yükü; hepsi mevcut model kataloğunun düşük maliyetli yönlendirme katmanında yer alan DeepSeek V4 Flash, Gemini 3.5 Flash ve Qwen3.7 Plus arasında devredilebilir.

Hız Sınırı Yönetimi Kontrol Listesi

Kategori	Ne kontrol edilmeli	Acil eylem	Uzun vadeli çözüm
İstek limitleri	RPM başlık değerleri, patlama sıklığı	İstemci isteklerini kısın, yerel bir hız sınırlayıcı ekleyin	Kullanıcı başına katmanlar, sunucu tarafı kuyruğa alma
Token limitleri	Model başına TPM bütçesi, çağrı başına ortalama token, yanıtla bildirilen kullanım	Tokenları önceden sayın, büyük istemleri bölün, sınıra yakın çağrıları geciktirin	Token bütçeleme ile toplu işleme, yüksek hacimli işleri daha düşük maliyetli modellere yönlendirin
Eşzamanlılık limitleri	Maksimum eşzamanlı akış veya bağlantı	İstemci başına eşzamanlı istekleri sınırlayın, boşta kalan akışları kapatın	Bağlantı havuzu oluşturma, kademeli akış başlatma
Kota / bakiye	Hesap bakiyesi, günlük harcama sınırları	Kredileri yükleyin, harcama eşiklerini ayarlayın	Düşük bakiye uyarıları, ön ödemeli otomatik yükleme

Tipik Limit Aralıkları: Neyi Doğrulayabiliriz, Neyi Doğrulayamayız

Bu konudaki ikincil aramalar genellikle "tipik" RPM/TPM sayılarından oluşan bir tablo ister. Bir tane icat etmeyeceğiz. Yayınlanan katman başına limitler sık sık değişir, hesap geçmişine ve kullanım katmanına göre farklılık gösterir ve bu makale için mevcut olan kanıtların bir parçası değildir.

Soru	Durum	Doğrulama adımı
Bir öncü model için "tipik" RPM limiti nedir?	Bu kanıt setinde doğrulanmadı	Sağlayıcınızın hesap panelini veya hız sınırı yanıt başlıklarını doğrudan kontrol edin
1M-bağlamlı bir model için "tipik" TPM limiti nedir?	Bu kanıt setinde doğrulanmadı	Kendi temel hattınızı oluşturmak için bir haftalık trafik boyunca yanıt başlıklarından gerçek kullanımı günlüğe kaydedin
Kullanım katmanı bu sayıları değiştirir mi?	Genel sağlayıcı davranışına göre makul, burada kıyaslanmadı	Sağlayıcı konsolunuzdaki mevcut katman limitlerini doğrulayın
TokenLab'in toplu limitleri yukarı akış sağlayıcı limitleriyle tam olarak eşleşiyor mu?	Bu kanıt setinde doğrulanmadı	Kapasite planlamasından önce TokenLab'in API dokümanlarında doğrulayın

Sınırlamalar

• GPT-5.5, Claude Opus 4.8, Gemini 3.5 Flash veya burada referans verilen başka hiçbir model için resmi RPM/TPM rakamları mevcut değildi. Yukarıdaki fiyatlandırma tablolarındaki her sayı bağlam penceresi boyutu ve token başına maliyettir, hız sınırı değildir.
• TokenLab'in ağ geçidinin hız sınırı başlıklarını her yukarı akış sağlayıcısında tam olarak birleştirip birleştirmediği veya bazılarını değiştirmeden geçirip geçirmediği bu kanıt setinde doğrulanmamıştır. Başlık ayrıştırmayı, mevcut ağ geçidi davranışını dokümanlarda doğrulayana kadar sağlayıcıya özel olarak değerlendirin.
• Bu makaledeki model isimleri 2026-07-07 tarihinde gözlemlenen ve 2026-07-14 tarihinde sona eren TokenLab model SSOT'unu yansıtır. Bir model dizisini kodlayan kod göndermeden önce model dizininde mevcut durumu doğrulayın.
• Token tahmin doğruluğu ile sağlayıcı tarafındaki sayım karşılaştırması bu kanıt setinde kıyaslanmamıştır. Kendi tahmincinizi, sabit bir sapmaya güvenmek yerine yanıtla bildirilen kullanıma göre kalibre edin.

SSS

İstek sayısı limitin altında olmasına rağmen uygulamam neden 429 hatası alıyor? Önce dakika başına token (TPM) bütçesini kontrol edin. Tek bir büyük istem, istek sayısı düşük kalsa bile token ödeneğini tüketebilir. Ayrıca eşzamanlılığı kontrol edin: açık akış bağlantıları, RPM ve TPM'nin her ikisi de iyi görünse bile yeni istekleri engelleyebilir.

429 aldığımda hemen yeniden denemeli miyim? Hayır. retry-after içinde belirtilen süreyi bekleyin veya bu başlık yoksa jitter ile üstel geri çekilme kullanın. Anında yeniden denemeler, "thundering-herd" (sürü etkisi) riski taşır ve kilitlenme sürenizi uzatabilir.

Yerel token sayımın, sağlayıcının bana faturalandıracağı şeyle eşleşip eşleşmeyeceğini nasıl bilebilirim? Tam olarak bilemezsiniz. İstemci tarafındaki tokenizer'lar yaklaşımlardır. Her yanıt gövdesinde döndürülen token kullanımını okuyun ve bunu zaman içinde tahmincinizi kalibre etmek için kullanın; istekleri tahmini tavanınızda göndermek yerine bir güvenlik marjı tutun.

TokenLab her modelde birleşik bir hız sınırı başlığı seti sunuyor mu? Burada mevcut olan kanıtlarda doğrulanmadı. Farklı yukarı akış sağlayıcıları farklı başlık formatları döndürür ve TokenLab'in ne kadar normalleştirme uyguladığı, varsaymak yerine mevcut API dokümanlarında doğrulanması gereken bir şeydir.

Planımı yükseltmeden hız sınırlarından nasıl kaçınabilirim? Token bütçeleme, yerel eşzamanlılık sınırları ve model yedeklemeyi birleştirin. Göndermeden önce tokenları tahmin edin, uzun istemleri bölün ve birincil limitinize ulaşıldığında, örneğin Claude Sonnet 5'ten DeepSeek V4 Pro'ya, alternatif bir modele yönlendirin.

Başlayın

Hız sınırları, AI API'leri üzerine inşa etmenin bir gerçeğidir, ancak kesintilere neden olmaları gerekmez. TokenLab'in ağ geçidi, mevcut model kataloğuna ve canlı fiyatlandırma ve verim verilerine erişmenizi sağlar, böylece limitleri tahmin etmek yerine etrafından dolaşabilirsiniz. Ayrıca toplayıcı ödünleşimlerini değerlendiriyorsanız, OpenRouter karşılaştırması yedekleme davranışını ve operasyonel yükü daha derinlemesine kapsar. API anahtarınızı tokenlab.sh adresinden alın ve yeniden deneme ve yedekleme mantığını sağlayıcı başına değil, bir kez oluşturun.