Limite de rată API

Elido limitează rata API-ului per cheie, nu per workspace. Asta înseamnă că fiecare integrare pe care o construiești poate satura propria limită fără a le afecta pe celelalte. Acest articol acoperă limitele per plan, headerele de citit și cum să te retragi curat.

Cifrele

Limite susținute per cheie:

Plan	Pe minut	Burst
Free	60	120
Pro	600	1200
Business	6000	12000

Burst-ul este ce poți depăși pe scurt într-o fereastră de 10 secunde. Regimul susținut este plafonul constant la care se reumple bucket-ul.

Nu există limite per endpoint — un GET /v1/links contează la fel ca un POST /v1/links. Singurele excepții sunt:

• POST /v1/bulk-import — 5 importuri active per workspace simultan.
• POST /v1/links cu un slug personalizat care intră în coliziune cu unul existent — acestea contează în continuare, dar nu returnează slotul în caz de conflict.
• GET /v1/analytics/timeseries cu interval=second — plafonat la 60/minut chiar și pe Business, pentru că interogarea ClickHouse subiacentă este mai costisitoare.

Headere de răspuns

Fiecare răspuns API include:

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

X-RateLimit-Reset este un timestamp Unix care indică momentul în care bucket-ul se reumple complet. Folosește-l pentru a programa reîncercări, nu întârzieri fixe.

Cum arată un 429

Când depășești limita:

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 este exprimat în secunde. Așteaptă atâta timp, apoi reîncearcă. SDK-urile fac asta automat, cu jitter; dacă scrii un client HTTP brut, procedează la fel.

Strategia de backoff

Dacă suprasoliciti API-ul (o operațiune în bloc unică, un backfill), ritmează clientul la limita de regim constant, nu la burst. O buclă naivă atinge plafonul de burst, apoi se blochează timp de 50 de secunde, apoi atinge din nou burst-ul — cu o medie mai proastă decât dacă ar ritma constant.

Pseudocod:

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

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

Acest tipar folosește 100% din limită cu zero erori 429.

Concurență

Cererile concurente partajează același bucket. Dacă trimiți 100 de cereri paralele dintr-un pool de workeri pe planul Pro (600/min), primele 100 reușesc instantaneu; bucket-ul se reumple apoi la 10/sec. Pool-ul tău de workeri ar trebui să vizeze o rată susținută, nu o adâncime de coadă.

Per cheie vs per IP

Bucket-ul este per cheie, nu per IP. Dacă folosești aceeași cheie de pe 10 mașini, cele 10 mașini partajează limita. Emite câte o cheie per mașină dacă ai nevoie de un plafon de 10× mai mare.

Nivelul de IP are o limită separată, foarte generoasă (10.000/min/IP), destinată doar opririi clienților scăpați de sub control. Nu o vei atinge niciodată în utilizare normală; dacă totuși se întâmplă, răspunsul este 429 cu corpul "error": "ip_rate_limited".

Cheile de idempotență nu ocolesc limita

Trimiterea repetată a aceleiași chei Idempotency-Key contează în continuare fiecare cerere în bucket-ul tău — putem returna răspunsul din cache fără a efectua operațiunea propriu-zisă, dar contorul crește. Nu folosi cheile de idempotență într-o buclă ca strategie de reîncercare.

Creșterea limitelor

Dacă folosirea ta necesită cu adevărat mai mult de 6000/min susținut, scrie la [email protected] cu:

• ID-ul workspace-ului tău.
• Numele integrării.
• Rata de cereri așteptată în regim constant și la vârf.
• Ce endpoint-uri (ca să putem planifica capacitatea pentru cele mai solicitate).

Acordăm creșteri de limită per cheie clienților enterprise cu contract, de obicei într-o zi lucrătoare.

Depanare

Primesc brusc 429 pe o cheie care funcționa înainte. Fie codul tău a început să intre într-o buclă (cel mai frecvent caz), fie altcineva din workspace a început să folosească aceeași cheie. Verifică tab-ul Usage al cheii API din dashboard pentru un grafic per minut.

429 la prima cerere a zilei. Bucket-urile de nivel Free se resetează pe o fereastră glisantă, nu la miezul nopții UTC. Dacă ai testat limita ieri la 23:59 și nu s-a reumplut complet până la 00:01, primul burst este încă limitat. Așteaptă 60 de secunde.

X-RateLimit-Remaining este negativ. Depășire de burst. Numărul îți arată cât de adânc în negativ te afli; înmulțește cu 60/limit pentru a obține secundele rămase până revii la zero.