Limite de rate API — request limits, headers si retry strategy

API-ul public SoftFactura aplică limite de rate (rate limiting) pentru a asigura performanta și disponibilitatea serviciului pentru toti utilizatorii. Acest articol explica limitele, cum le monitorizezi și cum să gestionezi situatiile când sunt atinse.

Limite active

Nivel	Limita	Fereastra
Short	30 cereri	per secunda
Medium	200 cereri	per 10 secunde
Long	1.500 cereri	per minut

Limitele se aplică per cheie API. Dacă ai mai multe chei API, fiecare are propriile limite independente.

Headers de rate limiting

Fiecare răspuns API include headers care îți arată situația curentă:

X-RateLimit-Limit: 1500
X-RateLimit-Remaining: 1487
X-RateLimit-Reset: 1713282060

Header	Semnificație
X-RateLimit-Limit	Numărul maxim de cereri permise în fereastra curentă
X-RateLimit-Remaining	Cereri ramase înainte de blocare
X-RateLimit-Reset	Timestamp (Unix) când se reseteaza contorul

Răspuns la depășire (429 Too Many Requests)

Când depășești limita, API-ul returnează:

HTTP/1.1 429 Too Many Requests
Retry-After: 5

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limita de cereri depasita. Reincercati dupa 5 secunde."
  }
}

Header-ul Retry-After indică numărul de secunde de asteptare înainte de a retrimite cererea.

Strategie de retry recomandată

Implementeaza un exponential backoff în aplicația ta:

1. La primul răspuns 429, așteaptă valoarea din Retry-After (sau 1 secunda dacă header-ul lipseste).
2. La al doilea 429 consecutiv, așteaptă 2 secunde.
3. La al treilea, așteaptă 4 secunde.
4. Continua să dublezi intervalul pana la maximum 60 de secunde.
5. După 5 incercari eșuate consecutive, logeaza eroarea și nu mai retrimite automat.

async function apiCallWithRetry(url, options, maxRetries = 5) {
  let delay = 1000;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const retryAfter = response.headers.get('Retry-After');
    const waitMs = retryAfter ? parseInt(retryAfter) * 1000 : delay;
    await new Promise(r => setTimeout(r, waitMs));
    delay = Math.min(delay * 2, 60000);
  }
  throw new Error('Rate limit depasit dupa ' + maxRetries + ' incercari');
}

Bune practici pentru a evita limitele

• Cache-uieste răspunsurile care nu se schimba frecvent (lista produse, detalii firma) — nu interoga API-ul de fiecare data.
• Folosește paginare eficienta — cere 50-100 de elemente per pagina în loc de cate 10.
• Grupeaza cererile — dacă ai mai multe operatii de creare, programează-le secvențial cu pauze scurte între ele.
• Monitorizează header-ul X-RateLimit-Remaining — când se apropie de 0, incetineste ritmul cererilor.
• Nu trimite cereri în paralel masiv — dacă ai nevoie de procesare bulk, contacteaza suportul pentru o soluție dedicata.