API rate limits

Elido rate-limit de API per sleutel, niet per workspace. Dat betekent dat elke integratie die je bouwt zijn eigen limiet kan verzadigen zonder de andere uit te hongeren. Dit artikel behandelt de limieten per abonnement, de te lezen headers en hoe je netjes terugschakelt.

De cijfers

Sustained-limieten per sleutel:

Abonnement	Per minuut	Burst
Free	60	120
Pro	600	1200
Business	6000	12000

Burst is wat je kort mag overschrijden binnen een venster van 10 seconden. Sustained is het steady-state-plafond waarop de bucket zich bijvult.

Er zijn geen limieten per endpoint — een GET /v1/links telt hetzelfde als een POST /v1/links. De enige uitzonderingen zijn:

• POST /v1/bulk-import — maximaal 5 actieve imports per workspace tegelijk.
• POST /v1/links met een custom slug die botst met een bestaande slug — deze tellen nog steeds mee, maar het slot wordt niet terugbetaald bij een conflict.
• GET /v1/analytics/timeseries met interval=second — beperkt tot 60/minuut, zelfs op Business, omdat de onderliggende ClickHouse-query zwaarder is.

Responseheaders

Elke API-response bevat:

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

X-RateLimit-Reset is een Unix-timestamp die aangeeft wanneer de bucket weer volledig is bijgevuld. Gebruik dit om retries in te plannen in plaats van vaste vertragingen.

Hoe een 429 eruitziet

Wanneer je de limiet overschrijdt:

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 is in seconden. Wacht zo lang en probeer het opnieuw. De SDK's doen dit automatisch met jitter; als je een raw HTTP-client schrijft, doe hetzelfde.

Backoff-strategie

Als je de API zwaar belast (een eenmalige bulktaak, een backfill), tim je client op de steady-state-limiet in plaats van de burst. Een naïeve loop raakt het burstplafond, stokt dan 50 seconden en raakt de burst opnieuw — gemiddeld slechter dan gewoon timen.

Pseudocode:

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

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

Dit patroon gebruikt 100% van de limiet met nul 429's.

Concurrency

Gelijktijdige requests delen de bucket. Als je 100 parallelle requests afvuurt vanuit een workerpool op het Pro-abonnement (600/min), slagen de eerste 100 direct; de bucket vult zich daarna aan met 10/sec. Je workerpool moet mikken op een sustained rate, niet op een wachtrijdiepte.

Per sleutel versus per IP

De bucket is per sleutel, niet per IP. Als je dezelfde sleutel vanaf 10 machines gebruikt, delen die 10 machines de limiet. Geef per machine een sleutel uit als je 10× meer ruimte nodig hebt.

De IP-laag heeft een aparte, zeer ruime limiet (10.000/min/IP) die alleen bedoeld is om weggelopen clients te stoppen. Je raakt deze in normaal gebruik nooit; als dat wel gebeurt, is de response 429 met de body "error": "ip_rate_limited".

Idempotency-keys omzeilen niets

Het herhaaldelijk versturen van dezelfde Idempotency-Key telt nog steeds elke request mee tegen je bucket — we kunnen de gecachete response teruggeven zonder het onderliggende werk te doen, maar de telling wordt wel verhoogd. Gebruik idempotency-keys niet als retry-strategie in een loop.

Limieten verhogen

Als jouw use case echt meer dan 6000/min sustained nodig heeft, mail dan [email protected] met:

• Je workspace-ID.
• De naam van de integratie.
• Verwachte steady-state- en piekrequestrate.
• Welke endpoints (zodat we capaciteit kunnen plannen voor de zware).

We verlenen per-sleutel limietverhogingen aan enterprise-klanten onder contract, meestal binnen één werkdag.

Problemen oplossen

Ineens 429's op een sleutel die eerder werkte. Of je code is in een loop terechtgekomen (meest voorkomend), of iemand anders in de workspace is dezelfde sleutel gaan gebruiken. Controleer het tabblad Gebruik van de API-sleutel in het dashboard voor een grafiek per minuut.

429's bij de eerste request van de dag. Buckets in de gratis laag resetten op een rollend venster, niet om middernacht UTC. Als je gisteren om 23:59 de limiet testte en de bucket is om 00:01 nog niet volledig bijgevuld, wordt de eerste burst nog steeds rate-limited. Wacht 60 seconden.

X-RateLimit-Remaining is negatief. Burst-overschrijding. Het getal geeft aan hoe diep je in het negatieve zit; vermenigvuldig met 60/limit om het aantal seconden tot je weer op nul staat te krijgen.