Limitare cereri

API-ul aplică mai multe limite suprapuse pentru a asigura utilizarea corectă pentru toți utilizatorii. Limitele se aplică per cheie API.

Limite implicite

Fereastră	Unități de cotă
Per minut	60 unități
Per oră	1.000 unități
Per zi	10.000 unități
Burst (per 10 secunde)	20 unități

Costul cererilor

Nu toate cererile costă la fel. Operațiunile mai grele consumă mai multe unități:

Endpoint	Cost
POST /api/upload	10 unități
DELETE /api/uploads/{slug}	3 unități
Toate celelalte endpoint-uri	1 unitate

Header-e de limitare

Fiecare răspuns de succes include header-e care vă permit să urmăriți cota rămasă:

Header	Descriere
X-RateLimit-Limit	Cota dvs. per minut
X-RateLimit-Remaining	Unități rămase în fereastra curentă de un minut
X-RateLimit-Reset	Timestamp Unix când se resetează fereastra curentă
X-RateLimit-Cost	Unități consumate de această cerere specifică

Depășirea limitelor

Când o limită este depășită, API-ul returnează 429 Too Many Requests cu un header Retry-After care indică numărul de secunde de așteptat înainte de a reîncerca.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{
  "error": "Rate limit exceeded (per minute)."
}

Comportament de încetinire progresivă

Când utilizarea per minut depășește 80% din cotă, API-ul introduce o întârziere progresivă a răspunsului de până la 2 secunde. Aceasta acționează ca un avertisment înainte ca limita strictă 429 să fie atinsă, oferind clienților bine comportați posibilitatea de a-și reduce ritmul.

Bune practici

• Citiți header-ul X-RateLimit-Remaining și reduceți ritmul cererilor când acesta se apropie de zero.
• Implementați retry cu întârziere exponențială la primirea unui 429.
• Folosiți GET /api/uploads cu paginare în loc de multe cereri GET /api/uploads/{slug} individuale.
• Dacă cerințele dvs. necesită limite mai mari, contactați-ne prin pagina de contact.