Hız sınırları¶

TEBHOS, HTTP API trafiğini işlem başına kovalar ve tek bir genel kova ile sınırlar. Kova, belirli bir zaman penceresinde izin verilen istek miktarıdır. Bu miktarı aşan istek 429 ile reddedilir; code alanı RATE_LIMITED olur ve yanıtta bir hız sınırı yanıt nesnesi ile hız sınırı başlıkları bulunur.

Kovalar nasıl çalışır¶

Her kova bir sızdıran kovadır (leaky bucket). Aynı anda en fazla kendi sınırı kadar isteği kabul eder, ardından pencere başına limit istek hızıyla sürekli boşalır. İzin verilen miktarı tüketen bir istemci, bunun yeterli bir kısmı boşalır boşalmaz yeniden istek gönderebilir; pencerenin tamamını beklemesi gerekmez.

Örneğin channel:message:create kovasının sınırı 10 saniyede 20'dir. Bir istemci art arda 20 mesaj gönderebilir; bundan sonra yaklaşık her 0,5 saniyede bir mesaj daha kabul edilir.

Kovalar ve anahtarlar¶

Çoğu işlem adlandırılmış bir kovayı denetler. Kova adının kendisi istemcilere gönderilmez; X-RateLimit-Bucket bu adın 16 karakterlik, sabit, onaltılık bir özetini taşır. Böylece istemci hangi işlemlerin aynı izin miktarını paylaştığını ayırt edebilir.

Her kova bir kimliğe göre anahtarlanır; dolayısıyla farklı çağıranların ayrı izin miktarları vardır. Anahtar işleme göre değişir ve kova tablolarında listelenir:

Bir bot ile sahibi farklı hesaplardır ve hiçbir zaman izin miktarı paylaşmaz.

Bazı işlemler birden fazla kovayı denetler; örneğin giriş (IP başına ve gönderilen giriş adı başına) ve grup DM oluşturma (DM kovası ile saatlik grup kovası). İstek, tüm kovalardan geçmelidir.

Genel sınır¶

/api/v1 altındaki her istek, istemci başına saniyede 50 istek sınırlı genel bir kovaya da sayılır. İstemci Authorization başlığıyla, bu başlığı göndermiyorsa IP adresiyle tanımlanır.

Şu istekler genel kovaya sayılmaz:

• CORS ön uçuş (OPTIONS) istekleri.
• Avatarlar, simgeler ve ekler gibi herkese açık medya için yapılan GET ve HEAD istekleri.
• Authorization başlığı olmadan gönderilen GET ve HEAD istekleri.
• Webhook yürütme (POST /webhooks/{webhook_id}/{token} ve entegrasyon varyantları) ile webhook mesajı okuma, düzenleme ve silme yolları. Bunların webhook başına kendi kovaları vardır.

Genel bir reddin gövdesinde global: true ve yanıtta X-RateLimit-Global: true başlığı bulunur. Genel red, kimlik bilgisini hiçbir zaman iptal etmez.

Hız sınırı yanıt nesnesi¶

429 gövdesi, sıradan hata yanıtının üyelerini ve iki ek üyeyi içerir.

{
  "error": "429 Too Many Requests",
  "code": "RATE_LIMITED",
  "message": "Hız sınırlamasına takıldın. 1 saniye sonra tekrar dene.",
  "global": false,
  "retry_after": 0.428
}

Yavaş mod reddi ise bunun yerine 400 SLOWMODE_RATE_LIMITED ile yanıt verir.

Hız sınırı başlıkları¶

TEBHOS hız sınırı başlıklarını yalnızca 429 yanıtında gönderir. Başarılı bir yanıt bu başlıkların hiçbirini taşımaz; bu nedenle kendi istek hızınızı izleyin ya da doğrudan 429'u işleyin.

API bu başlıkları farklı kökenden (cross-origin) çalışan tarayıcı istemcilerine açar; böylece bir web istemcisi bunları okuyabilir. En kesin değer yine gövdedeki retry_after alanıdır.

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Scope: user
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790000010
X-RateLimit-Reset-After: 9.5
X-RateLimit-Bucket: 5f0c1d2e3a4b5c6d
Content-Type: application/json

Hız sınırlarını işleme¶

async function tebhosFetch(url, init, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const body = await res.json().catch(() => ({}));
    const waitSeconds = body.retry_after ?? Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, waitSeconds * 1000));
  }
  throw new Error("Rate limited too many times");
}

import time, requests

def tebhos_request(method, url, attempts=5, **kwargs):
    for _ in range(attempts):
        res = requests.request(method, url, **kwargs)
        if res.status_code != 429:
            return res
        try:
            wait = res.json().get("retry_after")
        except ValueError:
            wait = None
        time.sleep(wait or float(res.headers.get("Retry-After", 1)))
    raise RuntimeError("Rate limited too many times")

Yavaş mod¶

Yavaş mod, bir hesabın bir sunucu kanalında ne sıklıkla mesaj gönderebileceğini sınırlar. İzin miktarı, kanalda yapılandırılan rate_limit_per_user saniyede bir mesajdır ve her hesap ile kanal için ayrı sayılır. Yalnızca aralığı sıfırdan büyük olan sunucu kanallarında geçerlidir; BYPASS_SLOWMODE iznine sahip bir üye (sunucu sahibi ve ADMINISTRATOR dahil) bundan muaftır.

Reddedilen bir gönderim 429 değil 400 SLOWMODE_RATE_LIMITED döndürür; gövdenin en üst düzeyinde kesirli saniye cinsinden bir retry_after ve tam saniye cinsinden bir Retry-After başlığı bulunur. Hiçbir X-RateLimit-* başlığı yoktur; bu sayede istemci, durum kodu ve hata koduna bakarak bunu bir kova reddinden ayırt edebilir.

{
  "error": "400 Bad Request",
  "code": "SLOWMODE_RATE_LIMITED",
  "message": "Yavaş mod hız sınırı.",
  "retry_after": 3.2
}

400 ile yanıt veren sınırlar¶

Profil alanı değişiklikleri alan başına 30 dakikada 25 değişiklik ile sınırlıdır. Sınır, hesap profiline ve her sunucu üyesi profiline ayrı ayrı uygulanır. Red, errors içinde code değeri alanı belirten tek bir girişle 400 INVALID_FORM_BODY döndürür. retry_after ve hız sınırı başlığı yoktur; kalan bekleme süresi yalnızca insanın okuyabileceği message içinde görünür.

Kova başvurusu¶

Aşağıdaki tablolar her kovayı sınırı, penceresi ve anahtarıyla birlikte listeler. Sınırlar API'de sabittir ve her hesaba uygulanır; hesap başına muafiyet yoktur. Hız sınırlaması yalnızca yerel geliştirme derlemesinde kapatılabilir, üretim örneğinde (instance) asla kapatılamaz.

Kimlik doğrulama¶

Hesap güvenliği¶

Kullanıcılar ve ilişkiler¶

Kanallar ve mesajlar¶

Sunucular¶

Webhook'lar¶

Webhook kovaları yoldaki webhook, kanal veya sunucuya göre anahtarlanır; bu nedenle tüm çağıranlar tarafından paylaşılır.

Uygulamalar, OAuth2 ve Gateway¶

Diğer¶

Diğer yüzeyler¶

Gateway'in identify işlemleri, komutlar ve yük boyutları için kendi sınırları vardır; bkz. Gateway sınırları ve hız sınırları. Bir yükleme URL'sine bayt yüklemek sayıca hız sınırına tabi değildir, ancak URL'nin süresi dolar; bkz. Ek yüklemeleri.