API hız sınırlama ve 429 yanıtlarını ele alma

API hız sınırlama neyi ifade eder?

IETF'nin HTTP standardına göre 429 Too Many Requests, kullanıcının belirli bir süre içinde çok fazla istek gönderdiğini belirtir. Yanıt, durumu açıklayan ayrıntılar içermelidir. Yeni bir istek göndermeden önce ne kadar bekleneceğini belirten Retry-After header'ını da içerebilir.

Standart, server'ın kullanıcıyı nasıl tanımlayacağını veya istekleri nasıl sayacağını belirlemez. İstek sayısı bir resource için, server'ın tamamı için ya da bir server grubu genelinde sınırlandırılabilir. Kullanıcıyı tanımlamak için kimlik doğrulama bilgileri veya durum tutan bir cookie kullanılabilir.

429 yanıtı cache içinde saklanmamalıdır. Bununla birlikte IETF, server'ların her durumda 429 kullanmasını zorunlu tutmaz. Bir saldırı sırasında veya tek bir taraftan çok fazla istek geldiğinde her isteğe bu yanıtı vermek de server üzerinde yük oluşturur. Server, bağlantıları bırakmak gibi başka adımlar uygulayabilir.

İstek hızı ve eş zamanlı istekler

Stripe, genel API hız sınırını bir hesap için toplam API kullanımına uygular. Bazı endpoint'lerin ayrıca kendi sınırları vardır. Stripe'ta adlandırılmış her API işlemi ayrı bir endpoint sayılır. Aynı endpoint'e farklı nesne kimlikleriyle gönderilen istekler ise o endpoint'in ortak sınırına dahil edilir.

Stripe, eş zamanlılık sınırını istek hızı sınırından ayrı ele alır. Hız sınırı genel olarak bir zaman aralığındaki istek sayısıyla ilgilidir. Eş zamanlılık sınırı ise belirli bir anda devam eden istekleri sayar. Uzun süren veya daha fazla işlem gerektiren istekler eş zamanlılık sınırına ulaşılmasına yol açabilir.

Stripe, liste isteklerini ve genişletme içeren istekleri bu duruma örnek verir. Bu istekler genel olarak daha fazla işlem gerektirir ve daha uzun sürebilir. Eş zamanlılık sınırları yalnızca ayrıca hız sınırı bulunan endpoint'lere değil, Stripe API genelindeki isteklere uygulanır. Sınırlar belirli endpoint'ler ve hesaplar için farklı olabilir.

Stripe, global-concurrency veya endpoint-concurrency yanıtı alındığında eş zamanlı isteklerin azaltılmasını ve exponential backoff ile jitter kullanılarak yeniden denenmesini belirtir. Uzun süren istekleri belirlemek için API isteklerinin süresinin ölçülmesini ve timeout'ların izlenmesini de önerir.

Stripe yanıtının nedenini ayırma

Stripe, hız sınırlamasına takılan isteklerde 429 ve nedeni açıklayan Stripe-Rate-Limited-Reason header'ını döndürür. Header değeri, sınırın bütün API kullanımıyla mı, belirli bir endpoint'le mi, eş zamanlı isteklerle mi ilgili olduğunu ayırt eder.

global-rate, hesabın genel hız sınırının aşıldığını belirtir. endpoint-rate, isteğin gönderildiği endpoint'in hız sınırına işaret eder. Stripe bu durumlarda sırasıyla genel istek hızının veya ilgili endpoint'e gönderilen isteklerin hızının düşürülmesini belirtir.

global-concurrency, genel eş zamanlılık sınırının aşıldığı anlamına gelir. endpoint-concurrency ise belirli endpoint'in eş zamanlılık sınırına karşılık gelir. İlk durumda toplam eş zamanlı istek sayısını, ikinci durumda ilgili endpoint'e yapılan eş zamanlı istek sayısını azaltmak Stripe'ın belirttiği yanıttır.

resource-specific, bir resource içindeki endpoint'lerle ilgili hız sınırının aşıldığını gösterir. Stripe buna aboneliklerin güncelleme ve oluşturma endpoint'lerini örnek verir. Bu değer için Stripe, ilgili resource içindeki endpoint'lere gönderilen isteklerin toplam hızını düşürmeyi belirtir.

Stripe'a göre bir 429 yanıtında bu header yoksa yanıt hız sınırından kaynaklanmamıştır. Olası nedenlerden biri lock_timeout hatasıdır. Stripe bazı işlemlerde aynı nesne üzerinde eş zamanlı çalışan işlemlerin tutarsız sonuç üretmesini önlemek için nesneyi kilitler. Başka bir yerde tutulan kilit zamanında alınamazsa istek timeout ile sonuçlanabilir.

Stripe bu başarısız istekleri işlemez ve onlara bir request ID atamaz. Aynı nesneye yönelik birden fazla eş zamanlı istekte lock_timeout sık görülüyorsa Stripe, isteklerin sırayla veya daha düşük hızda gönderilmesini belirtir. Aynı nesne üzerindeki değişikliklerin sıraya alınması da kilit çekişmesini azaltabilir.

Retry süresini belirleme

Stripe, hız sınırlamasını ele almak için 429 yanıtlarının izlenmesini ve bir retry mekanizması uygulanmasını belirtir. Önerdiği exponential backoff düzeninde yeniden denemeler arasındaki bekleme süresi artar. Beklemeye rastgelelik eklemek, çok sayıda isteğin aynı anda yeniden gönderilmesi durumunu önlemeye yöneliktir.

Stripe, trafik kontrolünün client tarafında da yapılabileceğini belirtir. Genel düzeyde trafik sınırlanabilir ve yoğun hız sınırlaması algılandığında istek hızı azaltılabilir. Stripe'ın API kullanımını kontrol etmek için verdiği yöntemlerden biri client tarafında token bucket algoritmasıdır.

GitHub REST API, primary rate limit ve secondary rate limit uygular. Primary sınır aşıldığında 403 veya 429 yanıtı döner ve x-ratelimit-remaining değeri sıfır olur. GitHub, isteğin x-ratelimit-reset alanındaki zamandan önce yeniden denenmemesini belirtir.

Secondary sınır aşıldığında da 403 veya 429 dönebilir. Bu durumda hata mesajı secondary sınıra ulaşıldığını belirtir. Yanıtta retry-after varsa GitHub, yeniden denemeden önce bu alandaki saniye sayısı kadar beklenmesini söyler. x-ratelimit-remaining sıfırsa bekleme, x-ratelimit-reset alanında belirtilen zamana kadar sürer.

Bu iki durum da geçerli değilse GitHub, yeniden denemeden önce en az bir dakika beklenmesini belirtir. Secondary sınır nedeniyle istek başarısız olmaya devam ederse retry aralıkları exponential olarak artırılır ve belirli sayıda denemeden sonra hata verilir. GitHub, sınıra takılmışken istek göndermeye devam etmenin entegrasyonun engellenmesine yol açabileceğini de belirtir.

GitHub yanıt header'larını okuma

GitHub, primary sınırın durumunu yanıtlarla gönderilen header'larda bildirir. x-ratelimit-limit, ilgili zaman aralığında yapılabilecek azami istek sayısını gösterir. x-ratelimit-remaining, aynı aralıkta kalan istekleri; x-ratelimit-used ise yapılmış istekleri gösterir.

x-ratelimit-reset, geçerli sınır penceresinin sıfırlanacağı zamanı UTC epoch saniyesi olarak verir. x-ratelimit-resource ise isteğin hangi rate limit resource için sayıldığını gösterir. GitHub, isteklerin hızını ve backoff süresini ayarlamak için bu header'ların kullanılmasını, ancak kalan istek sayısının tam bir değere sahip olmasına bağlı mantıktan kaçınılmasını belirtir.

GitHub, API isteklerini birden fazla bölgede işler. İsteği hangi bölgenin işlediğine bağlı olarak değerler yanıttan yanıta değişebilir. Aynı sınır penceresinde daha sonraki bir yanıtta x-ratelimit-remaining değeri daha yüksek olabilir.

GET /rate_limit, kimliği doğrulanmış kullanıcının resource grupları için genel bir görünüm sağlar. Bu endpoint'e yapılan çağrı primary sınıra dahil edilmez; secondary sınıra dahil edilebilir. GitHub'a göre yanıt header'ları geçerli durum için yetkili kaynaktır ve endpoint'in bildirdiği değerlerden farklı olabilir. İkisi uyuşmadığında GitHub, yanıt header'larının esas alınmasını belirtir.

Secondary sınırın durumunu sorgulamanın bir yolu yoktur. GitHub, bu sınıra çok fazla eş zamanlı istek, tek bir endpoint'e çok fazla istek veya kısa sürede çok fazla içerik oluşturulması gibi durumlarda ulaşılabileceğini belirtir. Açıklanmayan başka nedenlerle de secondary sınır uygulanabilir.

Sınırlar ve kapsam

OWASP'a göre API isteklerini karşılamak ağ bant genişliği, CPU, memory ve storage gibi kapasite gerektirir. Yalnızca belirli bir sürede yapılan istekleri saymak, tek bir isteğin içinde yürütülen işlem sayısını doğrudan sınırlamaz. OWASP'ın GraphQL örneğinde endpoint için hız sınırı ve yüklenen görselin boyut kontrolü vardır; ancak tek istekte uploadPic işleminin kaç kez denenebileceği sınırlandırılmamıştır. OWASP, bu durumun server memory'sinin tükenmesine yol açabileceğini belirtir.

OWASP, rate limiting'in iş ihtiyaçlarına göre ayarlanmasını ve bazı endpoint'ler için daha sıkı kurallar uygulanabileceğini söyler. Ayrıca tek bir API client veya kullanıcının belirli bir işlemi kaç kez ya da ne sıklıkla yapabileceğinin sınırlandırılmasını önerir. Tek kullanımlık kod doğrulama ve parola kurtarma isteği bu işlemlere verilen örneklerdir.

OWASP, istek gövdesi ve query string içindeki parametreler için server tarafında doğrulama yapılmasını da belirtir. Özellikle yanıtta döndürülecek kayıt sayısını belirleyen parametre bu kapsamda yer alır. Gelen parametreler ve payload'lar için string uzunluğu, array içindeki eleman sayısı ve yüklenen dosya boyutu gibi azami değerler tanımlanmasını önerir.