API hız limitleri (rate limit) ve kota yönetimi

Ayın son iş günü, saat 17.20. Ön muhasebe sorumlusu kapanış için siparişleri kontrol ederken son iki günün siparişlerinin CRM'e hiç düşmediğini fark ediyor. Entegrasyonu kuran ekibe soruyor, gelen cevap kısa: sistem limit veriyor. Gerçekte olan şu — sabah bir kişi raporlama için otuz bin kaydı dışa aktarmaya kalkmış, aynı saatlerde pazaryeri senkronu her zamanki gibi sipariş çekmeye devam etmiş, sağlayıcı ikisini de aynı kotadan saymış ve hesabı saatlerce yavaşlatmış. Sipariş kaybolmadı ama iki gün kimse onları görmedi: depo iki siparişi elle ikişer kez hazırladı, bir müşteriye aynı fatura iki kez gitti.

Hız limiti çoğu şirkette ancak böyle bir günün ardından gündeme gelir ve o gün de yanlış soruyla gelir: limitimizi nasıl yükseltiriz? Bu yazıda önce hız limiti ile kotanın neden farklı şeyler olduğunu, hangi limit tiplerinin sizi hangi belirtiyle vurduğunu, duvara çarpıldığında doğru davranışın ne olduğunu, isteklerin nasıl sıraya ve önceliğe bağlanacağını, istek sayısını gerçekten azaltan yöntemleri, kotanın paylaşılan bir kaynak gibi nasıl bütçeleneceğini, sorunu önceden haber veren izlemeyi, sağlayıcıya sorulması gereken soruları, gerçek zamanlılık tavsiyesinin sınırını ve kesinti anında verinin bütünlüğünü nasıl koruyacağınızı ele alıyoruz.

Güvenli bantAtıl kapasiteLimit duvarı

Hız limiti ile kota aynı şey değildir

Hız limiti bir hız göstergesidir: belirli bir zaman penceresinde kaç istek gönderebileceğinizi söyler. Kota ise bir depo göstergesidir: gün, ay veya sözleşme dönemi boyunca toplam ne kadar tüketebileceğinizi belirler. İkisi bağımsız çalışır ve birbirini kurtarmaz. Günlük kotanız bol olabilir ama dakikalık hız limitini aştığınız için sistem sizi durdurur; ya da yavaş ve düzenli çalışırken ayın yirmisinde kotanız biter ve geri kalan on gün boyunca senkron yürümez.

Bu ayrımın pratik sonucu şudur: iki sorunun çözümü de farklıdır. Hız limiti sorunları zamanlama ve sıralama ile çözülür — istekleri yayarsınız, kuyruğa alırsınız, gereksizleri atarsınız. Kota sorunları ise tasarımla çözülür; toplam tüketimi düşürmeden kota problemini çözemezsiniz, yalnızca erteleyebilirsiniz.

Limitlerin çoğu hesap düzeyinde değil, erişim anahtarı düzeyinde uygulanır. Bu ayrıntı ilk bakışta teknik görünür ama doğrudan operasyonel bir sonucu vardır: tek bir anahtarı bütün entegrasyonlarda paylaşırsanız, bir aracın hatası hepsini birden durdurur. Anahtarların nasıl ayrıştırılacağını ve yetkilerinin nasıl daraltılacağını API anahtarı ve güvenli erişim yönetimi yazısında ele alıyoruz.

Hangi limit tipi sizi hangi belirtiyle vurur?

Bir entegrasyon durduğunda ilk iş, hangi tür duvara çarptığınızı anlamaktır; çünkü belirti çoğu zaman sebebi gizler. Aşağıdaki tablo, sahada en sık görülen limit tiplerini ve bunların operasyona nasıl yansıdığını gösterir.

Limit tipi	Neyi sınırlar	Tipik belirti
Pencere bazlı hız	Saniye veya dakika içindeki istek sayısı	Toplu işlemin ilk saniyelerinde durma
Günlük kota	Yirmi dört saatteki toplam çağrı	Akşam saatlerinde senkronun sessizce kesilmesi
Eşzamanlılık	Aynı anda açık istek sayısı	Paralel çalışan işlerin birbirini bloke etmesi
Ağırlık puanı	İsteğin maliyeti, dönen kayıt sayısı	Az sayıda çağrıyla limitin dolması
Uç nokta bazlı pay	Tek bir uç noktanın kendi payı	Rapor çekimi sipariş senkronunu boğar
Kullanıcı bazlı pay	Kullanıcı başına düşen hak	Bir kişinin işi tüm ekibi durdurur

Bu tiplerin içinde en çok yanıltanı ağırlık puanıdır. İstek sayınız düşük olduğu halde limite takılıyorsanız, muhtemelen her çağrıda gereğinden fazla veri istiyorsunuzdur; beş yüz kaydı tek seferde çeken bir sorgu, sağlayıcının gözünde beş yüz küçük çağrıya bedel olabilir. Çok kanallı sipariş akışlarında bu durum özellikle sık görülür; pazaryeri tarafındaki senkron mantığını pazaryeri entegrasyonu yazısında ayrıntılı anlatıyoruz.

Duvara çarpınca doğru davranış nedir?

Sağlayıcı limiti aştığınızı söylediğinde iki seçenek vardır: beklemek veya ısrar etmek. Israr eden entegrasyonlar sorunu büyütür. Hata alan isteği hemen yeniden gönderen bir akış, saniyeler içinde kendi kendine bir yük saldırısına dönüşür; sağlayıcı da bu davranışı gördüğünde ceza süresini uzatır veya erişimi tamamen askıya alır. Bu yüzden sorunun büyük kısmı limitin kendisinden değil, limite verilen tepkiden doğar.

Doğru davranış kademeli geri çekilmedir: ilk denemeden sonra kısa, sonrakilerde giderek uzayan bekleme süreleri. Buna küçük bir rastgelelik eklemek de şarttır, yoksa aynı anda duran yüz iş aynı anda yeniden dener ve duvar tekrar örülür. Sağlayıcı yanıtında ne kadar bekleneceğini söylüyorsa, tahmin yürütmek yerine o süreye uyun.

Bir entegrasyonun kalitesi limit yokken ne kadar hızlı çalıştığıyla değil, limite çarptığında ne kadar sessizce toparlandığıyla ölçülür.

Her isteğin aciliyeti aynı değildir

Limit altında çalışmanın en az konuşulan yolu, isteklere öncelik vermektir. Bir müşteri web sitesinde form doldurduğunda o kaydın saniyeler içinde CRM'e düşmesi gerekir. Aynı anda çalışan aylık rapor dökümü ise yarım saat gecikse kimsenin haberi olmaz. İkisi aynı kuyrukta, aynı sırayla ilerliyorsa dar kapasiteyi rapor tüketir ve müşteri bekler.

Pratik kurulum üç kuyruk kullanır: gerçek zamanlı olması gereken olaylar, gün içinde tamamlanması yeterli olan senkronlar ve gece penceresine bırakılabilecek toplu işler. Her kuyruğa ayrı bir hız tavanı verirsiniz; toplamları sağlayıcı limitinin altında kalacak şekilde ayarlanır. Böylece yoğun bir gün, en kritik akışı değil en esnek olanı yavaşlatır. Bu tür kuyruk ve yeniden deneme mantığını hazır sunan ara katmanların ne zaman gerektiğini entegrasyon platformları yazısında karşılaştırıyoruz.

İstek sayısını gerçekten azaltan yöntemler

Limit yönetiminin büyük kısmı beklemeyi iyileştirmek değil, hiç göndermemektir. Aşağıdaki yedi yöntem, çoğu kurulumda tüketimi ciddi biçimde düşürür ve hiçbiri sağlayıcıdan izin istemez.

• Yoklama yerine olay bildirimi: Her beş dakikada bir yeni sipariş var mı diye sormak yerine, sipariş oluştuğunda karşı tarafın size haber vermesini isteyin; boşa giden sorguların neredeyse tamamı böyle kaybolur.
• Fark senkronu: Tüm kayıtları değil, son senkrondan sonra değişenleri çekin; bunun için karşı sistemde güncellenme zamanına göre filtreleme desteği aramanız yeterlidir.
• Toplu uç noktalar: Yüz kaydı yüz ayrı istekle göndermek yerine tek istekte gönderin; çoğu sağlayıcı toplu çağrıyı tek istek sayar, bazıları ağırlık puanı uygular ama yine de kazançlıdır.
• Alan daraltma: Yalnızca kullandığınız alanları isteyin; hem yanıt küçülür hem de ağırlık puanı uygulayan sistemlerde tüketim düşer.
• Önbellek: Ülke listesi, ürün kategorileri, vergi oranları gibi nadiren değişen verileri her seferinde çekmeyin; günde bir kez tazelemek yeterlidir.
• Yazma birleştirme: Bir kayıt üzerinde arka arkaya yapılan değişiklikleri tek güncellemede toplayın; kullanıcı bir formda beş alan düzeltirken karşı sisteme beş istek gitmesin.
• Pencere kaydırma: Zorunlu olmayan toplu işleri, sipariş ve talep trafiğinin düştüğü saatlere alın; aynı iş aynı kotayla ama kimseyi engellemeden biter.

Yoklamadan olay bildirimine geçmek en büyük kazancı sağlar, ama beraberinde bir sorumluluk getirir: gelen bildirimin gerçekten karşı sistemden geldiğini doğrulamanız gerekir. İmza doğrulama ve tekrar saldırısına karşı korumayı webhook güvenliği yazısında adım adım anlatıyoruz.

Kotayı paylaşılan bir kaynak gibi bütçeleyin

Şirket büyüdükçe API kotası, ofisteki internet hattına benzer: herkes kullanır, kimse ne kadar kullandığını bilmez ve biri ağır bir iş başlattığında herkes yavaşlar. Kotayı teknik bir ayar değil, paylaşılan bir kapasite olarak görmek bu noktada işleri değiştirir. Hangi entegrasyonun ne kadar tükettiğini ayrı ayrı ölçebiliyorsanız, tıkanma anında suçlu aramak yerine payları yeniden dağıtırsınız.

Bütçeleme basit bir tabloyla başlar: her entegrasyon için normal günlük tüketim, tepe gün tüketimi ve tolere edilebilir gecikme. Bu üç sayıyı yazmak, çoğu ekibin kotayı ilk kez gerçekten görmesini sağlar. Sonrasında karar kolaylaşır — hangi akış öncelikli, hangisi geceye kayabilir, hangisi bütünüyle gereksiz.

Asıl tehlike günlük trafik değil, tek seferlik işlerdir

Limit sorunlarının büyük kısmı normal operasyondan doğmaz. İlk veri aktarımı, on binlerce kaydın toplu güncellenmesi, yeni bir raporun geçmişe dönük beslenmesi, bir otomasyon senaryosunun döngüye girmesi — hepsi tek seferlik işlerdir ve hepsi kotayı bir günde tüketebilir. Bu yüzden kapasiteyi ortalama gününüze göre değil, en yoğun gününüze göre planlamak gerekir. Toplu aktarımların nasıl parçalara bölüneceğini ve hangi sırayla yürütüleceğini veri içe ve dışa aktarma yazısında ele alıyoruz.

Duvara çarpmadan önce nasıl haber alırsınız?

Çoğu ekip limit sorununu müşteri şikâyetiyle öğrenir, çünkü izleme kurulmamıştır ve entegrasyon başarısız olduğunda kimseye bir şey söylemez. Oysa uyarı eşiğini limitin dibine değil, yolun ortasına koymak gerekir: kotanın belirli bir bölümü tükendiğinde haber veren bir uyarı, duvara çarpmadan önce müdahale şansı bırakır.

İzlemede bakılacak üç şey vardır. Birincisi, limit hatalarının sayısı ve hangi uç noktada yoğunlaştığı. İkincisi, kuyrukta bekleyen iş sayısı; bu sayı gün içinde sürekli artıyorsa kapasiteniz artık talebi karşılamıyordur. Üçüncüsü, senkronun gecikmesi, yani bir olayın gerçekleşmesiyle karşı sisteme yansıması arasındaki süre. Bağlantı koptuğunda önce sizin haberdar olmanızı sağlayacak kurulum için entegrasyon izleme yazısına bakabilirsiniz.

Sağlayıcıya hangi soruları sormalısınız?

Entegrasyon kararını verirken limit koşullarını sormak, fiyatlandırmayı sormak kadar önemlidir ve çoğu şirket bunu atlar. Dokümantasyonda dört başlık aranmalıdır: limitlerin hangi düzeyde uygulandığı, aşım halinde ne kadar süre beklendiği, yanıtın bekleme süresini içerip içermediği ve toplu işlemler için ayrı bir yol sunulup sunulmadığı.

Bir soru daha vardır ve nadiren sorulur: limitler değiştiğinde nasıl haber veriliyor? Sağlayıcılar limitleri zaman içinde sıkılaştırır; önceden duyuru yapılmayan bir sıkılaştırma, dün çalışan entegrasyonu bugün durdurur. Aynı kırılganlık sürüm değişikliklerinde de yaşanır ve önlemi büyük ölçüde ortaktır; bu konuyu API sürüm değişiklikleri yazısında ayrıca ele aldık.

Her şey gerçek zamanlı olmalı mı?

Yaygın tavsiye tek yönde ilerler: veri ne kadar hızlı akarsa o kadar iyi. Pratikte bu tavsiyenin sınırı çok erken gelir. Bir işletmede gerçekten saniyelik gecikme isteyen akış sayısı azdır — gelen talep, ödeme onayı, stok düşümü gibi birkaç tanesi. Geri kalan her şey için on beş dakikalık bir gecikme kimsenin fark etmeyeceği bir farktır ve limit sorununun büyük kısmını kökünden çözer.

Bunun tersi de doğrudur ve gözden kaçar: bazı akışlarda gecikme değil, sıralama önemlidir. Sipariş güncellemesi siparişin kendisinden önce ulaşırsa hızlı çalışmanız hiçbir işe yaramaz. Hazır otomasyon platformlarında da limitin karşılığı görev kotasıdır; iki popüler yaklaşımın bu açıdan farklarını otomasyon platformu karşılaştırması yazısında inceledik.

Kesinti anında veriyi nasıl korursunuz?

Limit yüzünden yarıda kalan bir aktarımın en pahalı sonucu gecikme değil, çift kayıttır. İstek gönderilmiş, sağlayıcı işlemi yapmış, ama yanıt limit hatasıyla dönmüştür; entegrasyon bunu başarısız sayıp tekrar gönderir ve aynı sipariş sisteme iki kez düşer. Bu senaryo nadir değildir ve düzeltmesi her zaman elle yapılır.

Korunma yolu, her isteğe onu benzersiz kılan bir kimlik eklemektir; aynı kimlikle gelen ikinci istek yeni kayıt yaratmaz, ilkinin sonucunu döndürür. Sağlayıcı bunu desteklemiyorsa kendi tarafınızda bir eşleştirme anahtarı tutup yazmadan önce kontrol etmelisiniz. Aynı kaydın iki sistemde birden değişmesi durumunda hangi tarafın kazanacağını ise iki yönlü veri senkronizasyonu yazısında ele alıyoruz.

Nereden başlamalı?

Yeni bir entegrasyon kurarken limit tasarımını sona bırakmak yaygın bir hatadır; sona bırakıldığında kod yeniden yazılır. En hızlı yol üç adımdır. Önce mevcut tüketimi ölçün: hangi entegrasyon, hangi uç noktaya, günde kaç istek gönderiyor. Sonra bu isteklerin ne kadarının gereksiz olduğunu bulun; yoklama yapan ve hiçbir şey döndürmeyen sorgular çoğu kurulumda listenin başında çıkar. Son olarak kalan trafiği kuyruk ve önceliğe bağlayın.

Bu üç adımın hiçbiri sağlayıcıyla pazarlık gerektirmez ve çoğu durumda limit artırımı isteme ihtiyacını ortadan kaldırır. Limit artırımı istemek yanlış bir şey değildir; ancak tasarım sorununu para veya sözleşme ile çözmeye çalışmak, sorunu yalnızca bir sonraki büyüme adımına erteler. Analitik tarafındaki ağır sorguları operasyonel API'den ayırmak da bu mantığın parçasıdır; bu ayrımı veri ambarı entegrasyonu yazısında anlatıyoruz.

Hız limitleriyle boğuşmanın en pratik panzehiri, aynı işi yapan sistem sayısını azaltmaktır: satış, ön muhasebe ve raporlama aynı kayıt üzerinde çalıştığında sistemler arasında taşınacak veri de kendiliğinden azalır. Rocketly'de bu akışlar tek platformda toplandığı için dışarıya açılan entegrasyon sayısı sınırlı kalır; ücretsiz hesap açarak kendi entegrasyon haritanızı sadeleştirerek kurabilirsiniz.