Domain Name API Hız Sınırı (Rate Limit), Throttling ve Toplu Kullanım Politikası

Entegrasyonunuz büyüdüğünde akla gelen ilk soru hep aynıdır: “Saniyede kaç istek gönderebilirim?” Kısa yanıt: API anahtarı başına saniyede 1 istek. İkinci soru da genelde şudur: “Peki gece çalışan toplu tarama scriptim ne olacak?” Onun yanıtı da nettir: insan eliyle tetiklenmeyen her çağrı /api-bulk ucundan geçmelidir.

Bu sayfa, bu iki kuralın neden var olduğunu, HTTP 429 yanıtı aldığınızda tam olarak ne yapmanız gerektiğini ve entegrasyonunuzu ilk seferde doğru kurmanızı sağlayacak hazır kod örneklerini içerir. Domain Name API altyapısı kurumsal ölçekte yüksek erişilebilirlik için tasarlanmıştır; hız sınırları ise bu istikrarı tüm bayi ağı adına birlikte koruyan mekanizmadır.

İçindekiler

• Bir bakışta kurallar
• Hangi endpoint’i kullanmalıyım?
• Rate limit ve throttling nedir?
• Saniyede 1 istek pratikte ne anlama geliyor?
• HTTP 429 hatası nasıl çözülür?
• Kod örnekleri: C#, PHP, Python, Node.js
• İstek akış diyagramı
• Toplu entegrasyonda en iyi uygulamalar
• Sık yapılan entegrasyon hataları
• Otomatik izleme ve kötüye kullanım tespiti
• Sıkça sorulan sorular
• Daha yüksek hız sınırı nasıl talep edilir?

Bir Bakışta Kurallar

Hız sınırı, throttling ve endpoint kurallarının tamamı tek tabloda. Entegrasyon ekibinize bu tabloyu iletmeniz çoğu zaman yeterlidir.

Hangi Endpoint’i Kullanmalıyım?

İki endpoint de birebir aynı işlevi sunar; aradaki tek fark temel URI’dir. Doğru seçimi yapmak için tek bir soru sorun: bu isteği o anda bir insan mı tetikledi?

Ölçüt basittir: saniyede 1’den fazla otomatik istek üreten her senaryo toplu kullanımdır ve yalnızca /api-bulk üzerinden yürütülmelidir. Bu kural; kullandığınız async modelden, thread sayısından veya eşzamanlılık stratejinizden bağımsızdır.

Rate Limit ve Throttling Nedir?

Saniyede 1 İstek Pratikte Ne Anlama Geliyor?

Toplu işlerinizi planlarken en çok işinize yarayacak bilgi budur. Saniyede 1 istekle çalışan tek bir kuyruğun kaba süreleri şöyledir:

Buradan çıkan pratik sonuç şudur: toplu işlerinizi bir zaman penceresine yayın. Gecelik taramaları sabah 09:00’a yetiştirmeniz gerekiyorsa işi akşamdan başlatın, listeyi tek seferde sıkıştırmaya çalışmayın. Listenizdeki mükerrer kayıtları temizlemek çoğu entegrasyonda toplam süreyi tek başına gözle görülür şekilde kısaltır.

Eşzamanlılık kuralı

Sisteminiz çok thread’li ya da tamamen asenkron olsa bile, dışarı çıkan toplam istek hızı API anahtarı başına saniyede 1 isteği aşamaz.

• Paralel async çağrılar aynı sınıra dahildir; ayrı ayrı sayılmaz.
• Thread sayısını artırmak size ek kota kazandırmaz.
• Tüm thread ve worker’ların üzerinden geçtiği tek bir merkezi kuyruk veya hız sınırlayıcı kullanın.

HTTP 429 Hatası Nasıl Çözülür?

Entegrasyonunuz HTTP 429 Too Many Requests alıyorsa sırayla şunları yapın:

1. İstek göndermeyi hemen durdurun. 429 aldıktan sonra devam etmek kısıtlamayı derinleştirir.
2. Retry-After başlığını okuyun. Her 429 yanıtına eklenir ve kaç saniye beklemeniz gerektiğini saniye cinsinden bildirir.
3. En az 1 saniye bekleyin — Retry-After daha büyükse onu esas alın.
4. Başarısız isteği yeniden deneyin. Kayıt, yenileme ve transfer gibi durum değiştiren işlemlerde önce işlemin gerçekten başarısız olduğunu doğrulayın.
5. 429 sürüyorsa üstel geri çekilme uygulayın: 1 sn → 2 sn → 4 sn → 8 sn … 60 saniyede sınırlayın ve her beklemeye küçük bir rastgele gecikme (jitter) ekleyin.
6. Tüm otomatik çağrıların /api-bulk kullandığını doğrulayın. Tek bir unutulmuş cron job bile sürekli 429 üretebilir.
7. Toplam eşzamanlılığı ölçün. Tüm sunucu, thread ve worker’larınızdan çıkan isteklerin toplamı 1 istek/sn’yi geçmemelidir.

Kod Örnekleri: Doğru Yeniden Deneme Mantığı

Aşağıdaki örnekler; Retry-After okuma, üstel geri çekilme ve merkezi kuyruk mantığını en yaygın entegrasyon dillerinde gösterir. Hepsinde ortak fikir aynıdır: tek kapı, tek hız, sabırlı yeniden deneme.

C# (.NET entegrasyonları)

// C# — merkezi kuyruk + Retry-After destekli üstel geri çekilme
private static readonly SemaphoreSlim Gate = new(1, 1); // tüm worker'lar tek kapıdan geçer

// Not: HttpRequestMessage tek kullanımlıktır, her denemede yenisini üretin.
async Task<HttpResponseMessage> SendWithRetryAsync(Func<HttpRequestMessage> newRequest)
{
    var delay = TimeSpan.FromSeconds(1);
    var maxDelay = TimeSpan.FromSeconds(60);

    for (var attempt = 1; attempt <= 6; attempt++)
    {
        HttpResponseMessage response;

        await Gate.WaitAsync();
        try
        {
            response = await client.SendAsync(newRequest());
            await Task.Delay(1000); // saniyede 1 istek sınırı
        }
        finally
        {
            Gate.Release();
        }

        if ((int)response.StatusCode != 429)
            return response; // başarılı ya da farklı bir hata

        var retryAfter = response.Headers.RetryAfter?.Delta ?? delay;
        var wait = retryAfter > delay ? retryAfter : delay;

        await Task.Delay(wait + TimeSpan.FromMilliseconds(Random.Shared.Next(0, 250))); // jitter
        delay = TimeSpan.FromTicks(Math.Min(delay.Ticks * 2, maxDelay.Ticks));
    }

    throw new InvalidOperationException("Maksimum deneme sayısı aşıldı.");
}

PHP (WHMCS, WordPress, cPanel entegrasyonları)

// PHP — Retry-After destekli üstel geri çekilme
function sendWithRetry(string $url, array $headers, int $maxRetries = 5): array
{
    $delay = 1; // saniye

    for ($i = 0; $i < $maxRetries; $i++) {
        $response = httpRequest($url, $headers);

        if ($response['status'] !== 429) {
            return $response; // başarılı ya da farklı bir hata
        }

        $retryAfter = (int)($response['headers']['Retry-After'] ?? $delay);
        sleep(max($retryAfter, $delay));
        usleep(random_int(0, 250) * 1000);  // jitter
        $delay = min($delay * 2, 60);       // 60 saniyede sınırla
    }

    throw new RuntimeException('Maksimum deneme sayısı aşıldı.');
}

// Kuyruk tarafı: iki istek arasında en az 1 saniye bırakın.
foreach ($domains as $domain) {
    $result = sendWithRetry($baseUrl . '/api-bulk/...', $headers);
    sleep(1);
}

Python (script ve otomasyon)

# Python — Retry-After destekli üstel geri çekilme
import random, time, requests

def send_with_retry(url, headers, max_retries=5):
    delay = 1  # saniye
    for _ in range(max_retries):
        response = requests.get(url, headers=headers, timeout=30)

        if response.status_code != 429:
            return response  # başarılı ya da farklı bir hata

        retry_after = int(response.headers.get("Retry-After", delay))
        time.sleep(max(retry_after, delay) + random.uniform(0, 0.25))  # jitter
        delay = min(delay * 2, 60)

    raise RuntimeError("Maksimum deneme sayısı aşıldı.")

# Kuyruk: tek işçi, istekler arasında 1 saniye
for domain in domains:
    send_with_retry(f"{BASE_URL}/api-bulk/...", HEADERS)
    time.sleep(1)

Node.js (JavaScript / TypeScript)

// Node.js — sıralı kuyruk + Retry-After destekli üstel geri çekilme
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function sendWithRetry(url, options, maxRetries = 5) {
  let delay = 1000; // ms

  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response; // başarılı ya da farklı bir hata

    const retryAfter = Number(response.headers.get('retry-after')) * 1000;
    await sleep(Math.max(retryAfter || 0, delay) + Math.random() * 250); // jitter
    delay = Math.min(delay * 2, 60000);
  }

  throw new Error('Maksimum deneme sayısı aşıldı.');
}

// Promise.all ile paralel göndermeyin; sırayla ilerleyin.
for (const domain of domains) {
  await sendWithRetry(`${BASE_URL}/api-bulk/...`, options);
  await sleep(1000);
}

İstek Akış Diyagramı

Her toplu API isteği bu akışı izlemelidir. Entegrasyon ekibiniz için referans olarak saklayabilirsiniz.

              TOPLU API İSTEK AKIŞI

  +----------------------+
  |  Domain'i istek      |
  |  kuyruğuna ekle      |
  +----------+-----------+
             |
             v
  +----------------------+
  |  /api-bulk ucuna     |
  |  isteği gönder       |
  +----------+-----------+
             |
       +-----+------+
       |            |
     200 OK     429 Too Many Requests
       |            |
       v            v
   Sonucu       Retry-After başlığını oku
   işle         En az 1 saniye bekle
       |            |
       |            v
       |        Üstel geri çekilme uygula
       |        1sn -> 2sn -> 4sn -> 8sn
       |            |
       |            v
       |        İsteği yeniden dene
       |            |
       +-----+------+
             |
             v
  +----------------------+
  |  Kuyruktaki bir      |
  |  sonraki kayda geç   |
  +----------------------+

Toplu Entegrasyonda En İyi Uygulamalar

Sık Yapılan Entegrasyon Hataları

Otomatik İzleme ve Kötüye Kullanım Tespiti

Aşağıdaki davranışlar tüm API trafiğinde sürekli izlenir ve değerlendirme gerçek zamanlı olarak otomatik yapılır:

• Ölçülebilir sistem performansı düşüşüne yol açan yüksek hacimli trafik
• Aynı domain için tekrarlayan kayıt veya sorgulama denemeleri
• Başarısız isteklerin toplam içindeki payının yüksek olması
• Anormal veya şüpheli trafik örüntüleri
• Bağlantı kararsızlığı ve zaman aşımı anomalileri

Tespit edilen ihlallerde süreç kademelidir: önce throttling, tekrarı hâlinde geçici erişim kısıtlaması, ağır veya süregelen kötüye kullanımda ise hesabın kapatılması. İhlal anında etkilenen istekler ayrıca bildirim yapılmaksızın kısıtlanır veya engellenir.

Sıkça Sorulan Sorular

Paralel istek gönderebilir miyim?

Hayır. Thread sayısından veya async modelinden bağımsız olarak, dışarı çıkan toplam istek hızı API anahtarı başına saniyede 1 isteği aşamaz.

Sınırı aşmak için birden fazla API anahtarı kullanabilir miyim?

Hayır. Çoklu anahtar kullanımıyla sınır aşma girişimleri aktif olarak izlenir; hesap kapatılmasına kadar gidebilen bir politika ihlali sayılır.

Asenkron çalışmak kotamı artırır mı?

Hayır. Hız sınırı API anahtarına global olarak uygulanır; thread, coroutine veya sunucu başına değil.

429 yanıtını yok sayarsam ne olur?

429 sonrasında istek göndermeye devam etmek kısıtlamayı derinleştirir ve kademeli erişim sınırlamalarını tetikleyebilir. Doğru davranış, durup beklemek ve geri çekilerek tekrar denemektir.

Kısa süreli ani yığın isteklere (burst) izin var mı?

Hayır. Tek bir saniyeye sıkışan kısa istek patlamaları da hız sınırı ihlali olarak değerlendirilir.

Retry-After başlığı nedir?

Her 429 yanıtına eklenen ve yeniden denemeden önce kaç saniye beklemeniz gerektiğini saniye cinsinden bildiren HTTP başlığıdır. Her zaman dikkate alın; kendi sabit bekleme sürenizden büyükse onu esas alın.

Bu politika /api için de geçerli mi?

Evet. Saniyede 1 istek sınırı her iki endpoint için de geçerlidir ve /api’yi toplu işlemler için kullanmak ayrıca politika ihlalidir. Yaptırım otomatik ve gerçek zamanlıdır.

Bu sınırlar neden var?

Çünkü paylaşılan bir altyapıda tek bir entegrasyonun ürettiği yük, diğer tüm bayilerin yanıt süresine yansır. Hız sınırları; tüm bayiler için adil ve eşit erişimi, kurumsal ölçekte öngörülebilir performansı, istem dışı oluşan aşırı yüklenmelere karşı korumayı ve doğru kurgulanmış yüksek hacimli otomasyonların kesintisiz çalışmasını birlikte güvence altına alır.

Daha Yüksek Hız Sınırı Nasıl Talep Edilir?