API hız sınırları

Elido, API'yi çalışma alanı (workspace) başına değil, anahtar başına sınırlar. Bu, oluşturduğunuz her entegrasyonun diğerlerini aç bırakmadan kendi sınırını doyurabileceği anlamına gelir. Bu makale, plana göre sınırları, okunması gereken başlıkları ve temiz bir şekilde geri çekilmeyi (backoff) kapsar.

Rakamlar

Anahtar başına sabit-durum sınırları:

Plan	Dakika başına	Burst
Free	60	120
Pro	600	1200
Business	6000	12000

Burst, 10 saniyelik bir pencerede kısaca aşabileceğiniz miktardır. Sabit-durum ise kovanın (bucket) dolduğu sabit tavan değeridir.

Uç nokta (endpoint) başına sınır yoktur — bir GET /v1/links, bir POST /v1/links ile aynı sayılır. Tek istisnalar:

• POST /v1/bulk-import — çalışma alanı başına aynı anda en fazla 5 aktif içe aktarma (import).
• Mevcut bir slug ile çakışan özel bir slug'a sahip POST /v1/links — bunlar hâlâ sayılır ama çakışma durumunda hakkı iade etmez.
• interval=second parametreli GET /v1/analytics/timeseries — altta yatan ClickHouse sorgusu daha ağır olduğu için Business planında bile 60/dakika ile sınırlıdır.

Yanıt başlıkları

Her API yanıtı şunları içerir:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset, kovanın ne zaman tamamen dolacağını gösteren bir Unix zaman damgasıdır. Sabit gecikmeler yerine yeniden denemeleri planlamak için bunu kullanın.

429 nasıl görünür

Sınırı aştığınızda:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After saniye cinsindendir. O kadar bekleyin, sonra yeniden deneyin. SDK'lar bunu otomatik olarak jitter ile yapar; ham bir HTTP istemcisi yazıyorsanız aynısını yapın.

Geri çekilme (backoff) stratejisi

API'yi yoğun şekilde kullanıyorsanız (tek seferlik bir toplu iş, bir backfill), istemcinizi burst yerine sabit-durum sınırında hızlandırın. Saf bir döngü burst tavanına çarpar, ardından 50 saniye durur, sonra tekrar burst'e çarpar — bu, düzgün hızlandırmadan ortalamada daha kötüdür.

Sözde kod (pseudocode):

const limit = 600; // per minute
const delayMs = (60 * 1000) / limit; // 100ms between requests

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Bu desen, sınırın %100'ünü sıfır 429 ile kullanır.

Eşzamanlılık

Eşzamanlı istekler kovayı paylaşır. Pro plandaki (600/dk) bir worker havuzundan 100 paralel istek gönderirseniz, ilk 100 tanesi anında başarılı olur; kova daha sonra saniyede 10 hızında dolar. Worker havuzunuz bir kuyruk derinliğini değil, sabit bir hızı hedeflemelidir.

Anahtar başına vs. IP başına

Kova, IP başına değil anahtar başınadır. Aynı anahtarı 10 makineden kullanıyorsanız, 10 makine sınırı paylaşır. 10 kat marj gerekiyorsa makine başına bir anahtar oluşturun.

IP katmanının, yalnızca kaçak istemcileri durdurmak amacıyla ayrı, çok cömert bir sınırı vardır (10.000/dk/IP). Normal kullanımda buna asla çarpmazsınız; çarparsanız yanıt, gövdesinde "error": "ip_rate_limited" bulunan bir 429'dur.

Idempotency anahtarları atlatmaz

Aynı Idempotency-Key'i tekrar tekrar göndermek yine de her isteği kovanıza sayar — altta yatan işi yapmadan önbelleğe alınmış yanıtı döndürebiliriz, ama sayaç artar. Idempotency anahtarları üzerinde bir yeniden deneme stratejisi olarak döngü kurmayın.

Sınırları yükseltme

Kullanım senaryonuz gerçekten sabit-durumda 6000/dk'dan fazlasına ihtiyaç duyuyorsa, şunlarla birlikte [email protected] adresine e-posta gönderin:

• Çalışma alanı kimliğiniz (workspace ID).
• Entegrasyon adı.
• Beklenen sabit-durum ve tepe (peak) istek hızı.
• Hangi uç noktalar (ağır olanlar için kapasite planlayabilelim diye).

Anahtar başına sınır artışlarını sözleşmeli kurumsal müşterilere genellikle bir iş günü içinde veriyoruz.

Sorun giderme

Daha önce çalışan bir anahtarda aniden 429 almaya başladım. Ya kodunuz döngüye girmeye başladı (en yaygın), ya da çalışma alanındaki başka biri aynı anahtarı kullanmaya başladı. Panodaki API anahtarının Kullanım sekmesinde dakika başına bir grafik kontrol edin.

Günün ilk isteğinde 429 alıyorum. Ücretsiz katman kovaları, gece yarısı UTC'de değil kayan bir pencerede sıfırlanır. Dün saat 23:59'da sınırı test ettiyseniz ve saat 00:01'de tam dolmadıysa, ilk burst hâlâ hız sınırlıdır. 60 saniye bekleyin.

X-RateLimit-Remaining negatif. Burst aşımı. Sayı, ne kadar negatife indiğinizi söyler; sıfıra dönmeniz için gereken saniyeyi bulmak üzere 60/limit ile çarpın.