Hız limitleri: tüm limitler ve başlıklar

API’yi herkes için hızlı tutmak için LinkHarbor dakika başına istek sayısını sınırlar. Limitler planına bağlı değildir – aylık bir API çağrısı kotası yoktur. Bu makale tüm limitleri listeler ve kodunun bunları nasıl temiz şekilde ele alabileceğini gösterir.

#İstekler nasıl sayılır

• Her istek tam olarak bir kovaya düşer, örneğin kimliği doğrulanmış istekler için user veya token değişimi için token
• Sayım tam dakika başına yapılır (UTC); sayaç her yeni dakikada sıfırdan başlar
• Kovaya göre API çalışma alanı, kişi, bağlantı veya IP adresi başına sayar
• Daha token, kapsam veya şema aşamasında başarısız olan istekler (401, 403 insufficient_scope, 400, şema kontrolünden gelen 422 validation_failed) sayılmaz; 403 feature_not_available gibi sonraki hatalar sayılır

#Tüm limitler

#Çalışma alanı başına bir bütçe

Aynı çalışma alanındaki API anahtarlarından gelen tüm token’lar dakikada 600 isteği paylaşır – kaç anahtar oluşturduğundan bağımsız olarak. Bağlı yapay zekâ asistanlarının araçları da API’yi dahili olarak çağırdıkları için burada sayılır. Yani daha fazla anahtar limiti artırmaz. Çok fazla yük birkaç programa dağılıyorsa ortak bütçeye göre planla.

#Başlıklar

X-RateLimit-Limit

Kovanın dakika başına limiti, örneğin 600.

X-RateLimit-Remaining

Geçerli dakikada kaç istek kaldığı.

X-RateLimit-Bucket

İsteğin düştüğü kova, örneğin user.

Retry-After

Yalnızca 429 rate_limited ile: sonraki dakikanın başlamasına kalan saniye. api_key_locked ile bekleme süresi details.retry_after_sec içindedir.

#Limite ulaşıldığında

Limite ulaşıldığında API HTTP 429 ve bu gövdeyle yanıt verir. message içindeki metin hesap dilindedir (bkz. API hata biçimi), burada İngilizce. rate_limited koduna güven:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Bucket: user

{ "error": "rate_limited", "message": "Too many requests. Please try again in a moment.", "retry_after_sec": 37 }

1. Retry-After veya retry_after_sec değerini oku
2. En az o kadar saniye bekle, tüm işlemler aynı anda yeniden başlamasın diye biraz rastgelelik ekleyerek
3. İsteği en fazla birkaç kez yeniden dene
4. Sürekli 429 alıyorsan işi daha uzun bir süreye yay

const BASE = 'https://dock.at-harbor.com';
let cached = null; // { token, expiresAt }

async function getToken() {
  if (cached && Date.now() < cached.expiresAt - 60_000) return cached.token;
  const res = await fetch(BASE + '/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      key_id: process.env.LH_KEY_ID,
      key_secret: process.env.LH_KEY_SECRET,
    }),
  });
  if (!res.ok) throw new Error('Token exchange failed: HTTP ' + res.status);
  const data = await res.json();
  cached = { token: data.token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

async function lh(method, path, body, attempt = 0) {
  const headers = { Authorization: 'Bearer ' + (await getToken()) };
  if (body !== undefined) headers['Content-Type'] = 'application/json';

  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });

  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get('Retry-After') ?? 5);
    await new Promise((r) => setTimeout(r, (wait + Math.random() * 2) * 1000));
    return lh(method, path, body, attempt + 1);
  }
  if (res.status === 401 && attempt === 0) {
    cached = null; // token’ın süresi doldu – yeni bir token’la bir kez daha dene
    return lh(method, path, body, attempt + 1);
  }
  const data = await res.json().catch(() => null);
  if (!res.ok) throw new Error((data && data.error) + ' (HTTP ' + res.status + ')');
  return data;
}

// Örnek: const { items } = await lh('GET', '/v1/pages');

#Büyük veri miktarları için ipuçları

• Token’ı önbelleğe al ve yalnızca 15 dakika sonra süresi dolmadan kısa süre önce yenile
• X-RateLimit-Remaining değerini izle ve azaldığında yavaşla
• İstekleri düzinelerce paralel bağlantı yerine art arda gönder
• Listeleri her sayfayı tek tek sorgulamak yerine bir kez yükle ve yerel olarak filtrele
• Büyük senkronizasyonları birkaç dakikaya yay
• 5xx hatalarını artan aralarla yeniden dene, ama 4xx hatalarını deneme

#Diğer limitler

Token değişimindeki hatalı denemeler anahtarı ve IP’yi geçici olarak kilitler, bkz. API anahtarları ve token’lar. Anlık bildirimleri yalnızca panelde gönderirsin; limitleri Takipçiler ve anlık bildirimler bölümünde anlatılıyor.

Planının içerik limitleri – sayfalar, bağlantılar, bloklar, kısa bağlantılar vb. – hız limiti değil sabit üst sınırlardır. Planların karşılaştırması bölümünde listeleniyor.

#İstek boyutu

Her gövde API onu okumadan önce ölçülür. Ne kadar büyük olabileceği uç noktaya bağlıdır:

Gövde daha büyükse API 413 request_too_large ile yanıt verir; details.max_bytes ve details.max_kb limiti belirtir. Bir yüklemede çok büyük bir dosya 413 payload_too_large ile sonuçlanır. DELETE çağrıları gibi gövdesiz uç noktalar gövde kabul etmez ya da yalnızca {} kabul eder.

HTTP/1.1 413 Payload Too Large

{ "error": "request_too_large", "message": "…", "details": { "max_bytes": 65536, "max_kb": 64 }, "request_id": "…" }

Gövdenin içinde de limitler vardır: her metnin bir azami uzunluğu, her listenin bir azami giriş sayısı vardır ve bilinmeyen alanlar reddedilir. Değerler API referansında uç nokta başına listelenir. Bir ihlal 422 validation_failed ile sonuçlanır ve details alanı, kuralı ve limiti belirtir. Bir isteğin yolu ve sorgu dizesi birlikte en fazla 16 KB uzunluğunda olabilir.