API rate limit nasıl çalışır?

API rate limit, bir istemcinin belirli bir zaman aralığında kaç istek gönderebileceğini sınırlayan kurallardır. Limit aşıldığında API genellikle isteği reddeder ve istemcinin daha sonra tekrar denemesini bekler. Uygulama tarafında amaç, 429 yanıtlarını kontrollü biçimde ele almak, aynı isteği gereksiz yere tekrarlamamak ve limit dolmadan istekleri kuyruğa almaktır.

API rate limit nasıl çalışır?​

Bir API sağlayıcısı limiti kullanıcı, API anahtarı, IP adresi, hesap, endpoint veya bunların birleşimine göre uygulayabilir. Örneğin bir istemciye belirli bir süre içinde 100 istek hakkı tanımlanır. Bu haklar sabit zaman penceresinde sıfırlanabilir veya token bucket gibi sürekli yenilenen bir modelle yönetilebilir.

İstemci limit içindeyse normal yanıt alır. Limit aşıldığında en yaygın sonuç HTTP 429 Too Many Requests yanıtıdır. Yanıtta bazen yeniden denemeden önce beklenecek süreyi belirten Retry-After başlığı bulunur. Bu başlık yoksa istemci, artan bekleme süreleriyle yeniden denemeli ve deneme sayısını sınırlamalıdır.

Somut örnek​

Varsayımsal olarak bir API, aynı anahtar için 60 saniyelik pencerede 100 istek kabul etsin. Uygulamanız ilk 100 isteği gönderir; 101. istek limit dışındaysa API bunu reddeder. Uygulama 101. isteği hemen art arda göndermeye devam ederse sorun çözülmez ve başka bir geçici engelle karşılaşabilir.

Doğru davranış şudur: Yanıtın 429 olduğunu algılamak, varsa Retry-After değerini okumak, belirtilen süre kadar beklemek ve isteği yalnızca güvenli bir deneme sayısı içinde tekrar göndermek. Bekleme süresinde yeni istekleri doğrudan göndermek yerine kuyruğa almak daha sağlıklıdır.

Uygulamada izlenecek adımlar​

1. API dokümantasyonundaki limitin hangi birime uygulandığını belirleyin: istemci, kullanıcı, IP, anahtar, endpoint veya genel hesap limiti.
2. Her istekte HTTP durum kodunu ve varsa rate limit başlıklarını kaydedin; API anahtarını veya kişisel yanıt verisini günlükten ayırın. Başlık adları API'ye göre değişebileceği için tek bir sabit başlığa körü körüne güvenmeyin.
3. 429 yanıtında önce Retry-After değerini değerlendirin. Değer saniye sayısı veya HTTP tarihi olabilir; örneğin Retry-After: 120 en az 120 saniye beklemeyi ister. Değer geçersiz veya yoksa sağlayıcının kuralına göre başlangıç beklemesi seçin; artan beklemeye rastgele sapma (jitter) ve toplam süre/deneme sınırı ekleyin.
4. Tekrar denemeyi yalnızca geçici hatalara ve yeniden gönderilmesi güvenli isteklere uygulayın. Bir oluşturma işlemi iki kez çalışarak çift kayıt üretebiliyorsa idempotency anahtarı veya uygulamaya uygun başka bir tekrar güvenliği mekanizması kullanın.
5. Eşzamanlı istek sayısını sınırlayın. Birden fazla iş parçacığı aynı rate limit'i paylaşıyorsa her biri kendi sayacını kullanmak yerine ortak bir kota veya merkezi kuyruk kullanın.
6. Limit yaklaşırken yeni istekleri bekletin, önceliklendirin veya birleştirin. İşlem tamamlandığında 429 sayısını, bekleme süresini ve başarısız kalan işleri gözlemleyin.

Bir istemcinin yalnızca hata aldıktan sonra yavaşlaması yerine, bilinen kota ve yanıt başlıklarını kullanarak önceden hız sınırlaması yapması daha verimlidir. Örneğin saniyede çok sayıda istek gönderen bir iç servis, istekleri doğrudan paralel çalıştırmak yerine sınırlı bir kuyruktan çıkarabilir.

Limit türlerini ayırt etme​

Aşağıdaki ayrım, hangi çözümün uygulanacağını seçmeyi kolaylaştırır.


Bu modellerin dışarıdan ayırt edilmesi her zaman mümkün olmayabilir. Bu nedenle uygulama, dokümantasyondaki kuralları temel almalı; gözlemlenen yanıtları yalnızca teşhis amacıyla kullanmalıdır.

Sık yapılan hatalar​

429 yanıtını normal başarı gibi işlemek: Yanıt gövdesi okunmadan işlem başarılı kabul edilirse veri kaybı veya eksik senkronizasyon oluşabilir.

Sabit ve kısa aralıklarla sonsuz tekrar denemek: Bu yaklaşım rate limit'i daha da zorlar. Bekleme süresi artmalı ve toplam deneme sayısı sınırlı olmalıdır.

Yalnızca istemci tarafında sayaç tutmak: Birden fazla sunucu veya süreç aynı API anahtarını kullanıyorsa yerel sayaçlar gerçeği yansıtmayabilir.

Tüm hataları yeniden denemek: Kimlik doğrulama, yetki, geçersiz parametre veya kalıcı uygulama hataları genellikle bekleyince düzelmez. Bu yanıtlar için isteği düzeltmek veya işlemi sonlandırmak gerekir.

Sık sorulan sorular​

Rate limit ile günlük kota aynı şey midir?​

Sağlayıcı bu adları farklı kullanabilir. Günlük istek kotası da uzun bir zaman penceresindeki sınırdır; ayrıca saniyelik/dakikalık hız ve eşzamanlılık sınırları bulunabilir. Günlük hakkınız dururken kısa süreli sınıra takılmanız mümkündür.

Hız sınırı her API’de yalnızca 429 ile mi bildirilir?​

Hayır. Örneğin bazı sağlayıcılarda hız sınırı 403 ile de bildirilebilir; her 403 ise hız sınırı değildir. Durum kodunu sağlayıcının hata gövdesi ve kota başlıklarıyla birlikte okuyun. Yetki hatasını bekleyerek çözmeye çalışmayın.