SaaS API oran sınırlamaları: kullanıcı, organizasyon ve IP modelleri

Müşterilerin limitlerden neden kafası karışır

Oran limitleri ve kotlar benzer görünür, bu yüzden insanlar genellikle aynı şeymiş gibi davranır. Oran limiti, bir API'yi ne kadar hızlı çağırabileceğinizdir (saniye veya dakika başına istek). Kota ise daha uzun bir dönemde ne kadar kullanabileceğinizi sınırlar (günlük, aylık veya fatura döngüsü başına). İkisi normaldir, ama kurallar görünür olmadığında rastgeleymiş gibi hissedilir.

Klasik şikayet şudur: “dün çalışıyordu.” Kullanım nadiren dengelidir. Kısa bir ani artış, günlük toplamları iyi görünse bile birini sınırın üzerine çıkarabilir. Günde bir kez rapor çalıştıran bir müşteriyi hayal edin; bugün iş zaman aşımının ardından yeniden deniyor ve 2 dakikada 10 kat daha fazla çağrı yapıyor. API onları engeller ve gördükleri tek şey ani bir başarısızlıktır.

Hatalar belirsiz olduğunda kafa karışması daha da kötüleşir. API 500 döndürürse veya genel bir mesaj veriyorsa, müşteriler hizmetinizin kapalı olduğunu varsayar, sınırı aştıklarını değil. Acil destek talepleri açarlar, geçici çözümler geliştirirler veya sağlayıcı değiştirirler. Hatta 429 Too Many Requests bile ne yapılacağını söylemiyorsa sinir bozucu olabilir.

Çoğu SaaS API'si trafiği iki farklı nedenle sınırlar:

• Kötüye kullanımı durdurmak: scraping, brute force veya kontrolden çıkan betiklere karşı sistemi korumak.
• Normal kullanımı şekillendirmek: özellikle yoğun saatlerde herkes için performansı dengede tutmak.

Bu amaçları karıştırmak kötü tasarımlara yol açar. Kötüye kullanım kontrolleri genellikle per-IP veya per-token şeklinde olur ve sert olabilir. Normal kullanım şekillendirme genellikle per-user veya per-organization şeklindedir ve neyin aşıldığı, ne zaman sıfırlanacağı ve tekrar nasıl kaçınılacağı konusunda açık rehberlik sunmalıdır.

Müşteriler limitleri tahmin edebildiğinde buna göre plan yaparlar. Tahmin edemediklerinde her ani artış bozuk bir API gibi gelir.

Kimi/neyi koruduğunuza karar verin

Oran limitleri sadece bir gaz kesici değildir. Bir güvenlik sistemidir. Sayıları seçmeden önce neyi korumaya çalıştığınız konusunda net olun; çünkü her hedef farklı limitlere ve beklentilere yol açar.

Erişilebilirlik genellikle ilk gelir. Birkaç istemci trafiği patlattığında API'nizi zaman aşımına sokuyorsa herkes zarar görür. Buradaki limitler sunucuları patlamalar sırasında yanıt verir durumda tutmalı ve isteklerin birikmesine izin vermek yerine hızlıca başarısız olmalıdır.

Maliyet birçok API'nin arkasındaki sessiz etmendir. Bazı istekler ucuzdur, bazıları pahalıdır (LLM çağrıları, dosya işleme, depolama yazmaları, ücretli üçüncü taraf sorguları). Örneğin Koder.ai gibi bir platformda tek bir kullanıcı sohbet tabanlı uygulama üretimi sırasında birçok model çağrısı tetikleyebilir. Pahalı eylemleri izleyen limitler sürpriz faturaları önleyebilir.

Kötüye kullanım yüksek meşru kullanımdan farklı görünür. Credential stuffing, token tahmini ve scraping genellikle dar bir IP veya hesap kümesinden gelen çok sayıda küçük istekte görünür. Burada sıkı limitler ve hızlı bloklama istersiniz.

Çok kiracılı (multi-tenant) sistemlerde adalet önemlidir. Gürültülü bir müşteri herkesin performansını düşürmemeli. Pratikte bu genellikle katmanlı kontroller anlamına gelir: dakikadan dakikaya API'yi sağlıklı tutmak için bir patlama koruyucusu, pahalı uç noktalar veya eylemler için bir maliyet koruyucusu, kimlik doğrulama ve şüpheli desenlere odaklı bir kötüye kullanım koruyucusu ve tek bir kuruluşun diğerlerini baskılamasını engelleyen bir adalet koruyucusu.

Basit bir test yardımcı olur: bir uç noktayı seçin ve "Bu istek 10× artarsa önce ne bozulur?" diye sorun. Cevap hangi koruma hedefine öncelik vereceğinizi ve hangi boyutun (kullanıcı, org, IP) limiti taşıması gerektiğini söyler.

Doğru sınırlama boyutlarını seçin

Çoğu ekip bir limitle başlar ve sonra bunun yanlış insanları etkilediğini keşfeder. Amaç, gerçek kullanıma uyan boyutları seçmektir: kim çağırıyor, kim ödeme yapıyor ve neyin kötüye kullanım gibi göründüğü.

SaaS'ta yaygın boyutlar şunlardır:

• Kullanıcı başına: aynı hesap içindeki tek bir ağır son kullanıcının diğerlerini yavaşlatmasını engeller.
• Organizasyon/çalışma alanı başına: bir kiracının toplam kullanımına net bir tavan koyar (çoğu zaman faturalama planlarının sattığı şey budur).
• IP başına: botları, credential stuffing'i ve bir adresten gelen kötü yapılandırılmış istemcileri yakalar.
• API anahtarı/token başına: "kullanıcı" anlamlı olmadığında veya paylaşıldığında ortaklıklar ve entegrasyonlar için faydalıdır.

Kullanıcı başına limitler bir tenant içindeki adaletle ilgilidir. Bir kişi büyük bir dışa aktarma çalıştırıyorsa, yavaşlama takımın geri kalanından daha çok onu etkilemeli.

Organizasyon başına limitler bütçe ve kapasite ile ilgilidir. On kullanıcı aynı anda işler çalıştırsa bile, kuruluşun hizmetinizi veya fiyat varsayımlarınızı bozacak seviyelere çıkmaması gerekir.

IP başına limitler güvenlik ağı olarak düşünülmelidir, faturalama aracı olarak değil. IP'ler paylaşılıyor olabilir (ofis NAT, mobil taşıyıcılar), bu yüzden bu limitleri cömert tutun ve bunları daha çok bariz kötüye kullanımı durdurmak için kullanın.

Boyutları birleştirdiğinizde, birden fazla limit uygulandığında hangisinin "kazandığına" karar verin. Pratik bir kural: ilgili herhangi bir limit aşıldıysa isteği reddedin ve en kullanışlı nedeni döndürün. Bir çalışma alanı org kotasını aştıysa, kullanıcıyı veya IP'yi suçlamayın.

Örnek: Koder.ai'de Pro planlı bir çalışma alanı, org başına sürekli bir yapı isteği akışına izin verirken aynı anda tek bir kullanıcıyı dakikada yüzlerce istekten sınırlayabilir. Bir ortak entegrasyon tek bir paylaşılan token kullanıyorsa, per-token limiti etkileşimli kullanıcıları boğmasını engelleyebilir.

Üretimde işe yarayan algoritmalar

Çoğu oran sınırlama problemi matematikle ilgili değildir. Müşterilerin API'nizi nasıl çağırdığıyla uyumlu davranışı seçmek ve yük altındaki davranışı öngörülebilir tutmakla ilgilidir.

Token bucket yaygın bir varsayılandır çünkü kısa patlamalara izin verirken uzun vadeli sabit bir ortalamayı zorlar. Bir kullanıcı panoyu yenileyince 10 hızlı istek tetikleyebilir. Token bucket bunu, token'leri biriktirmişlerse yapmalarına izin verir, sonra onları yavaşlatır.

Leaky bucket daha sıkıdır. Trafiği sabit bir çıkışa düzeltir; bu, backend'inizin patlamalara dayanamayacağı durumlarda (örneğin pahalı rapor üretimi) yardımcı olur. Dezavantajı, patlamaların kuyruklanmaya veya reddedilmeye dönüşmesi nedeniyle müşterilerin bunu daha erken hissetmesidir.

Pencere tabanlı sayıcılar basittir, ama detaylar önemlidir. Sabit pencereler kenar noktaları yaratır (kullanıcı 12:00:59'da patlayabilir ve 12:01:00'da tekrar patlayabilir). Kaydırmalı pencereler daha adil gelir ve sınır patlamalarını azaltır, ancak daha fazla durum veya daha iyi veri yapıları gerektirir.

Ayrı bir limit sınıfı eşzamanlılıktır (in-flight istekler). Bu, yavaş istemci bağlantılarından ve uzun süren uç noktalardan sizi korur. Bir müşteri dakikada 60 istek içinde kalsa da aynı anda 200 isteği açık tutarak sizi aşırı yükleyebilir.

Gerçek sistemlerde ekipler genellikle küçük bir kontrol setini birleştirir: genel istek hızı için token bucket, yavaş veya ağır uç noktalar için eşzamanlılık sınırı ve uç nokta grupları (ucuz okuma vs maliyetli dışa aktarımlar) için ayrı bütçeler. Sadece istek sayısına göre sınırlama yaparsanız, pahalı bir uç nokta her şeyi boğabilir ve API rastgele kırık hissedebilir.

Fiyatlama ve kullanım ile eşleşen kotaları tasarlamak

İyi kotalar adil ve öngörülebilir hisseder. Müşteriler sadece engellendikten sonra kuralları keşfetmemeli.

Ayrımı net tutun:

• Kısa vadeli oran limitleri (örneğin 10 istek/saniye) patlamalara karşı hizmetinizi korur.
• Daha uzun vadeli kotalar (günlük/aylık) maliyetleri korur ve fiyat katmanlarını karşılaştırılabilir tutar.

Birçok SaaS ekibi her ikisini birlikte kullanır: patlamaları durdurmak için kısa bir oran limiti artı fiyatlandırmaya bağlı aylık kota.

Sert vs yumuşak limit seçimi çoğunlukla destek kararıdır. Sert limit hemen engeller. Yumuşak limit önce uyarmayı, sonra engellemeyi tercih eder. Yumuşak limitler, kullanıcıların bir hatayı düzeltmeleri veya yükseltme yapmaları için şans verdiği için sinirli destek taleplerini azaltır.

Birisi üstüne çıktığında davranış koruduğunuz şeye uygun olmalıdır. Aşırı kullanım diğer kiracıları zarar veriyorsa engelleme işe yarar. Daha yumuşak bir seçenek olarak işlem yavaşlatma veya düşük öncelik verme hareketi işleri akışta tutabilir. "Sonra fatura etme" kullanışlı olabilir, eğer kullanım öngörülebilir ve faturalama akışınız zaten varsa.

Katman bazlı limitler, her katmanın "beklenen kullanım şekline" sahip olması durumunda en iyi çalışır. Ücretsiz katman küçük aylık kotalar ve düşük patlama oranları verebilir; Business ve Enterprise katmanları daha yüksek kotalar ve daha yüksek patlama limitleri verir ki arka plan işleri hızlıca bitirebilsin. Bu, Koder.ai'nin Free, Pro, Business ve Enterprise planlarının farklı beklentiler koymasına benzer.

Kurumsal için erken desteklenen özel limitler değerlidir. Temiz bir yaklaşım "plan bazlı varsayılanlar, müşteri bazlı geçersizlemeler" şeklindedir. Her org için (ve bazen uç nokta bazında) yönetici tarafından ayarlanmış bir geçersizleme saklayın ve plan değişiklikleri sırasında bunun korunmasını sağlayın. Ayrıca kimin değişiklik isteyebileceğini ve bunların ne kadar hızlı yürürlüğe gireceğini kararlaştırın.

Örnek: bir müşteri ayın son gününde 50.000 kayıt içe aktarıyor. Aylık kotası neredeyse doluysa, %80–90 bandında bir yumuşak uyarı onlara durma zamanı verir. Saniye başına kısa bir oran limiti içe aktarmanın API'yi doldurmasını engeller. Onaylı bir org geçersizlemesi (geçici veya kalıcı) işi devam ettirir.

Adım adım: SaaS API'de limitleri uygulamak

Ne sayacağınızı ve bunun kime ait olacağını yazmakla başlayın. Çoğu ekip üç kimlik ile sonuçlanır: oturum açmış kullanıcı, müşteri organizasyonu (veya çalışma alanı) ve istemci IP'si.

Pratik bir plan:

• Kimlik kurallarını tanımlayın: auth'tan kullanıcı ID'si, token veya API anahtarından org ID'si, IP'yi ilk güvenilen proxy hop'undan alın (hangi başlığa güvendiğinizi açıkça belirtin).
• Uç noktaları maliyete göre gruplayın: okuma, yazma, ağır dışa aktarma, auth akışları. Her grup için farklı limitler verin ki tek bir pahalı uç nokta tüm bütçeyi tüketmesin.
• Sayaçların nerede duracağını seçin: tek bir örnek için bellek-içi, birçok sunucu arasında paylaşılan limitler için Redis, ve yalnızca daha yavaş, denetim amaçlı kotalar için veritabanı. Pencereye uygun TTL'ler kullanın (örneğin dakikalık limitler için 60 saniye).
• Tutarlı uygulayın: IP seli için kenarda (gateway/CDN) kaba engelleme, sonra route ve tenant'ı görebildiğiniz uygulama ara yazılımında daha ince per-user/org kontrolleri yapın.
• Her şeyi ölçümleyin: bloke oranını (429'lar), limiter'in eklediği gecikmeyi ve en çok bloke edilen anahtarları izleyin. Bloklar patladığında veya Redis hataları "fail open/closed" davranışına neden olduğunda alarm kurun.

Limitleri ayarlarken, tek bir küresel sayı yerine katmanları ve uç nokta gruplarını düşünün. Yaygın bir hata, birden fazla uygulama sunucusu arasında bellek-içi sayaçlara güvenmektir. Sayaçlar uyuşmaz ve kullanıcılar "rastgele" 429'lar görür. Redis gibi paylaşılan bir depo örnekler arasında limitleri istikrarlı tutar ve TTL'ler veriyi küçük tutar.

Dağıtım önemli. "Sadece raporla" modunda başlayın (ne bloke edileceğini kaydedin), sonra bir uç nokta grubunu zorlayın, sonra genişletin. Bu, destek biletleri dalgasıyla uyanmanızı engeller.

Yanıtlar ve başlıklarla limitleri anlaşılır kılmak

Bir müşteri limite takıldığında en kötü sonuç kafa karışıklığıdır: "API'niz mi kapandı yoksa ben mi yanlış yaptım?" Net, tutarlı yanıtlar destek biletlerini keser ve insanların istemci davranışını düzeltmesine yardımcı olur.

Engelliyorsanız HTTP 429 Too Many Requests kullanın. Gövdeyi tahmin edilebilir tutun ki SDK'lar ve panolar bunu okuyabilsin.

Aşağıda per-user, per-org ve per-IP limitleri için iyi çalışan basit bir JSON biçimi var:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for org. Try again later.",
    "limit_scope": "org",
    "reset_at": "2026-01-17T12:34:56Z",
    "request_id": "req_01H..."
  }
}

Başlıklar mevcut pencereyi ve istemcinin sonraki adımda ne yapabileceğini açıklamalıdır. Eğer birkaç tane ekleyecekseniz, buradan başlayın: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After ve X-Request-Id.

Örnek: bir müşterinin cron işi her dakika çalışıyor ve aniden başarısız olmaya başlıyor. 429 ile birlikte RateLimit-Remaining: 0 ve Retry-After: 20 döndüğünde, bunun bir limit olduğunu ve kesinti olmadığını hemen anlarlar; tekrar denemelerini 20 saniye geciktirebilirler. X-Request-Id'yi destekle paylaşırlarsa olayı hızlıca bulabilirsiniz.

Bir detay daha: başarılı isteklere de aynı başlıkları döndürün. Müşteriler sınırın yakınında olduklarını bunu görerek fark edebilirler.

İstemci davranışı: yeniden deneme, backoff ve güvenli yazmalar

İyi istemciler limitleri adil hissettirir. Kötü istemciler geçici bir limiti bir kesintiye çevirir çünkü daha sert şekilde vurmaya başlarlar.

429 aldığınızda bu yavaşlamanız gerektiğine dair bir işarettir. Yanıt ne zaman yeniden denenebileceğini söylüyorsa (örneğin Retry-After ile), en azından o kadar bekleyin. Söylemiyorsa üstel backoff ve jitter kullanın ki binlerce istemci aynı anda yeniden denemesin.

Yeniden denemeleri sınırlayın: denemeler arasındaki gecikmeyi sınırlayın (örneğin 30–60 saniye) ve toplam yeniden deneme süresini sınırlayın (örneğin 2 dakika sonra durup hatayı gösterin). Ayrıca olayları limit detaylarıyla kaydedin ki geliştiriciler sonradan ayar yapabilsin.

Her şeyi yeniden denemeyin. Birçok hata değişiklik veya kullanıcı eylemi gerektirir: 400 doğrulama hataları, 401/403 auth hataları, 404 bulunamadı ve 409 çatışmalar gerçek iş kurallarını yansıtıyordur.

Yazma uç noktalarında yeniden denemeler risklidir (oluşturma, ücretlendirme, e-posta gönderimi). Bir zaman aşımı olduğunda istemci yeniden denemeye kalkarsa çoğaltmalar oluşabilir. Idempotency anahtarları kullanın: istemci mantıksal bir eylem için benzersiz bir anahtar gönderir, sunucu aynı anahtar için tekrarları aynı sonuçla yanıtlar.

İyi SDK'lar geliştiricilerin gerçekten ihtiyaç duyduğu bilgileri sunarak bunu kolaylaştırabilir: durum (429), ne kadar bekleyeceği, isteğin yeniden denenmesinin güvenli olup olmadığı ve "Org için oran limiti aşıldı. 8s sonra yeniden deneyin veya eşzamanlılığı azaltın." gibi bir mesaj.

Kızgın biletlere yol açan yaygın hatalar

Limitlerle ilgili çoğu destek bileti limitin kendisiyle ilgili değildir. Sürprizlerle ilgilidir. Kullanıcılar bir sonraki adımda ne olacağını tahmin edemiyorsa API'nin bozuk veya adaletsiz olduğunu varsayarlar.

Sadece IP tabanlı limitler kullanmak sık yapılan bir hatadır. Birçok ekip tek bir genel IP arkasında oturur (ofis Wi‑Fi, mobil taşıyıcılar, bulut NAT). IP ile sınır koyarsanız, yoğun bir müşteri aynı ağa bağlı herkesin önünü kesebilir. Per-user ve per-org limitlerini tercih edin; per-IP'yi daha çok kötüye kullanım için bir güvenlik ağı yapın.

Bir diğer sorun tüm uç noktaları eşit görmek. Ucuz bir GET isteği ile ağır bir dışa aktarma işi aynı bütçeyi paylaşmamalı. Aksi takdirde müşteriler normal gezinme yaparken paylarını tüketir, sonra gerçek bir görev denediklerinde engellenirler. Uç nokta gruplarına göre ayrı kovalar kullanın veya istekleri maliyete göre ağırlıklandırın.

Sıfırlama zamanlaması da açık olmalı. "Günlük sıfırlanır" yeterli değildir. Hangi zaman dilimi? Kaydırmalı pencere mi yoksa gece yarısı sıfırlama mı? Takvim bazlı sıfırlama yapıyorsanız zaman dilimini söyleyin. Kaydırmalı pencereler kullanıyorsanız pencere uzunluğunu belirtin.

Son olarak, belirsiz hatalar kaosa yol açar. 500 veya genel JSON dönmek insanları daha çok yeniden denemeye iter. 429 kullanın ve RateLimit başlıklarını ekleyin ki istemciler akıllıca geri çekilebilsin.

Örnek: bir ekip Koder.ai entegrasyonu paylaşılan bir kurumsal ağdan inşa ederse, yalnızca IP sınırlaması tüm kuruluşu engelleyebilir ve bu rastgele kesintiler gibi görünür. Net boyutlar ve net 429 yanıtları bunu engeller.

Göndermeden önce hızlı kontrol listesi

Herkes için limitleri etkinleştirmeden önce, öngörülebilirliğe odaklanan son bir kontrol yapın:

• Limitleri fiyatlandırma katmanına ve uç nokta grubuna göre tanımlayın (auth, okuma, yazma, dışa aktarma). Giriş/yenileme gibi temel işlemler için küçük bir güvenlik tamponu bırakın.
• Kimlik kurallarını deterministik ve belgelenmiş yapın. Tam olarak nasıl saydığınızı karar verin (kullanıcı, org, API anahtarı, IP) ve önceliğin ne olduğunu belirtin.
• 429 yanıtlarını kendi başına açıklayıcı yapın. Retry-After ve RateLimit başlıklarını (Limit, Remaining, Reset) ekleyin. JSON gövdede kısa bir mesaj, hangi limitin aşıldığı ve ne zaman tekrar deneneceğini belirtin.
• Hem patlamaları hem yanlış pozitifleri izleyin. 429 oranını uç nokta grubuna, en çok çağıranlara ve başarılı isteklerdeki ani düşüşlere göre takip edin. Bloklar arttığında alarm kurun.
• Bir istisna planınız olsun: beyaz listeler, geçici artışlar, acil geçersizlemeler ve bunları kimin onaylayacağı.

Bir içgüdü testi: ürününüzün Free, Pro, Business ve Enterprise gibi katmanları varsa (Koder.ai gibi), normal bir müşterinin dakikada ve günde ne yapabileceğini düz bir dille açıklayabilmelisiniz ve hangi uç noktaların farklı muamele gördüğünü söyleyebilmelisiniz.

Bir 429'u açıkça açıklayamıyorsanız, müşteriler bunun hizmeti korumak değil, bozuk bir API olduğunu varsayar.

Örnek dağıtım planı ve sonraki adımlar

Bir B2B SaaS'ı düşünün: insanlar bir çalışma alanı (org) içinde çalışıyor. Birkaç güçlü kullanıcı ağır dışa aktarımlar çalıştırıyor ve birçok çalışan tek bir paylaşılan ofis IP'si arkasında oturuyor. Sadece IP ile sınır koyarsanız tüm şirketleri engellersiniz. Sadece kullanıcı bazlı limit koyarsanız tek bir betik yine çalışma alanını zedeleyebilir.

Pratik bir karışım:

• Kısa patlamalar için kullanıcı başına limit.
• Uzun vadede adil kalmak için org başına sürdürülebilir limit.
• Sızan tokenleri, botları ve gürültülü paylaşılan ağları yakalamak için per-IP kötüye kullanım koruması.

Birisi limite takıldığında mesajınız ne olduğunu, sonraki adımı ve ne zaman yeniden denenebileceğini söylemeli. Destek şu tür bir ifadeyi arkasında durabilecek durumda olmalı:

"Çalışma alanı ACME için istek hızı aşıldı. 23 saniye sonra yeniden deneyebilirsiniz. Bir dışa aktarma çalıştırıyorsanız eşzamanlılığı 2'ye düşürün veya işinizi yoğun olmayan saatlere planlayın. Normal kullanımı engelliyorsa, çalışma alanı ID'niz ve zaman damgası ile cevap verin, kotalarınızı gözden geçirebiliriz."

Bu mesajı Retry-After ve tutarlı RateLimit başlıklarıyla eşleştirin ki müşteriler tahminde bulunmak zorunda kalmasın.

Sürprizleri önleyen bir dağıtım: önce sadece gözlem modu, sonra uyar (başlıklar ve yumuşak uyarılar), sonra uygulama (429'lar ile net tekrar deneme zamanları), sonra katmana göre eşik ayarı ve büyük lansmanlar ve müşteri onbording'lerinden sonra gözden geçirme.

Bu fikirleri çalışır koda hızlıca dönüştürmek isterseniz, Koder.ai (koder.ai) gibi bir vibe-coding platformu kısa bir rate limit spesifikasyonu taslak hâline getirip Go middleware üretebilir.