
Teknik not
Yapay Zekâ API 429 Hatası: Retry-After ve Güvenli Yeniden Deneme

Bir yapay zekâ API’sine birkaç istek gönderdikten sonra 429 Too Many Requests hatasıyla karşılaşmak yaygındır. Çözüm, isteği hemen tekrar tekrar göndermek değildir: bu davranış sınırı daha da zorlayabilir. Önce hatanın geçici bir hız sınırı mı, hesap kotası mı olduğunu ayırın; ardından sunucunun bekleme önerisini ve sınırlı bir tekrar deneme planını uygulayın.

Rate limit 429 hatası neden oluşur?
API sağlayıcıları trafiği genellikle dakika başına istek (RPM) ve token (TPM) gibi ölçülerle sınırlar. Bazı servislerde model, proje veya kuruluş için farklı eşikler uygulanır. Bu nedenle az sayıda büyük istek de, çok sayıda küçük istek de sınırı aşabilir. Ani trafik artışı da geçici sınırlamaya yol açabilir. Örneğin OpenAI, slow_down durumunun istek ve token sınırlarının altında bile, trafiğin çok hızlı artırılmasıyla görülebileceğini belirtiyor. OpenAI hız sınırı belgeleri başlıklar ve hata kodlarıyla teşhis adımlarını açıklar.
Her 429 hatası bekleyip geçmez
HTTP durum kodu tek başına yeterli değildir. Yanıt gövdesindeki hata türünü ve varsa Retry-After başlığını da okuyun. Geçici hız sınırında bu başlık beklenmesi gereken süreyi söyleyebilir. Ancak kimi sağlayıcılarda 429, harcama kotasının dolduğunu da gösterebilir; böyle bir durumda başlık bulunmayabilir ve tekrar denemek erişimi geri getirmez. Anthropic hata belgeleri, 429 hız sınırı ile harcama sınırının ayrılmasını özellikle açıklar.
Geçici model yoğunluğu ayrıca 503 gibi farklı bir yanıtla bildirilebilir. Sağlayıcının hata kodunu inceleyin; kimlik doğrulama (401), yetki (403), hatalı istek (400) veya işlem gerektiren kota hatalarını otomatik tekrar listesine almayın.
Güvenli yeniden deneme akışı
- Hata türünü sınıflandırın. Yalnızca geçici hız sınırı veya geçici servis yoğunluğu gibi yeniden denenebilir durumları seçin.
Retry-Aftervarsa bekleyin. Bu süreyi alt sınır kabul edin; daha erken göndermeyin. Eşzamanlı istemcilerin aynı anda yüklenmemesi için üzerine küçük bir rastgele gecikme ekleyin.- Başlık yoksa exponential backoff ve jitter kullanın. Her başarısız denemede üst bekleme sınırını artırın, bekleme süresini bu aralıktan rastgele seçin.
- Deneme ve toplam süre sınırı koyun. Birkaç denemeden sonra veya isteğin zaman bütçesi dolunca durun. Sunucunun istediği bekleme süresi bütçenizi aşıyorsa isteği kuyruğa alıp daha sonra işleyin.
- İstek hızını azaltın. Kuyruk ve eşzamanlı istek sınırı kullanın; hata oranı yükselirse trafiği düşürün, normale döndüğünde kademeli artırın.
Basit bir bekleme örneği
Aşağıdaki TypeScript işlevi, geçici hata olduğu doğrulandıktan ve tekrar deneme sınırı kontrol edildikten sonra kullanılabilir. retryAfterSeconds sunucu başlığından ayrıştırılmış değerdir; başlık yoksa tam jitter uygular:
const baseMs = 500;
const maxDelayMs = 30_000;
async function waitBeforeRetry(
attempt: number,
retryAfterSeconds?: number,
) {
const exponentialCap = Math.min(
maxDelayMs,
baseMs * 2 ** attempt,
);
const delayMs = retryAfterSeconds !== undefined
? retryAfterSeconds * 1000 + Math.random() * 300
: Math.random() * exponentialCap;
await new Promise(resolve => setTimeout(resolve, delayMs));
}
Bu işlev tek başına hangi hatanın yeniden denenebilir olduğuna karar vermez. Önce hata kodunu inceleyin; tekrar deneme sayısını ve toplam süreyi sınırlayın. OpenAI belgeleri, başarısız isteklerin de dakika sınırına katkıda bulunabileceğini ve üst üste tekrarların çözüm olmadığını belirtiyor. Resmî rate limit rehberindeki örnekleri kendi SDK sürümünüzün otomatik retry davranışıyla birlikte değerlendirin.
Üretimde gözden kaçan iki ayrıntı
SDK ve uygulama retry’larını çarpmayın
Kullandığınız SDK bazı geçici hataları kendisi tekrar deneyebilir. Uygulama katmanında da aynı döngüyü sınırsızca kurarsanız deneme sayısı katlanır. Tek bir katmanda retry yönetin veya SDK ve uygulama sınırlarını birlikte hesaplayın. Bekleme süresi sunucunun önerdiği sınırı aşıyorsa daha erken denemek yerine işi erteleyin.
Akış başladıktan sonra isteği körlemesine yeniden oynatmayın
Streaming yanıtta kullanıcıya kısmi metin ulaştıktan sonra isteğin tamamını yeniden göndermek, ekranda yinelenen yanıt veya yinelenen işlem oluşturabilir. Akış başladıktan sonra gelen hataları, kullandığınız API’nin stream olaylarına göre yönetin. OpenAI de kısmi çıktı tüketildikten sonra isteğin otomatik olarak baştan oynatılmaması gerektiğini belirtiyor.
Kısa kontrol listesi
- HTTP durum kodunun yanında hata gövdesindeki
typevecodealanlarını okuyun. Retry-Afterve rate limit reset başlıklarını izleyin.- Geçici 429/503 durumlarını sınırlı denemeyle; kota, kimlik doğrulama ve hatalı istekleri ise düzeltme gerektiren durumlar olarak ele alın.
- İstek kimliği, hata kodu, deneme sayısı ve bekleme süresini kaydedin; API anahtarını ve kullanıcı istemlerinin tamamını loglara yazmayın.
- Önce düşük eşzamanlılıkla başlayıp gerçek hata oranına göre trafiği artırın.
Resmî kaynaklar: OpenAI API rate limits, Anthropic API rate limits ve Anthropic API errors.