Limite de cereri pentru un API SaaS B2B: cum stabilești cotele și explici eroarea 429
Un ghid practic pentru fondatorii SaaS B2B: ce măsori înainte de a fixa o cotă API, cum separi clienții și operațiunile costisitoare și ce trebuie să primească integrarea la eroarea 429.

Echipa Pentru Fondatori
Platforma fondatorilor din România

O limită de cereri API trebuie să protejeze serviciul fără să oprească o integrare normală a clientului. Pentru un SaaS B2B, întrebarea utilă nu este „câte cereri pe minut au alții?”, ci câte cereri face efectiv fiecare client, cât costă operațiunile respective și ce se întâmplă când o aplicație depășește pragul. O cotă copiată de la un furnizor mare poate bloca un import legitim sau poate lăsa necontrolat un export scump.

Imagine editorială generată cu OpenAI; grafic ilustrativ, fără date reale.
Măsoară mai întâi traficul și costul unei cereri
Începe cu jurnalele API: numără cererile pe client, pe integrare și pe endpoint, separat pentru orele obișnuite și vârfurile scurte. Un client care sincronizează comenzi o dată la zece minute are alt profil decât unul care importă un catalog la lansare. Păstrează în analiză durata cererii, mărimea răspunsului, numărul de înregistrări întoarse și cererile care folosesc servicii plătite separat. Identificatorii și volumele ajută; valorile secrete ale cheilor API nu au ce căuta în jurnal.
OWASP include în riscul de consum necontrolat al resurselor și limitele pentru durata execuției, fișiere încărcate, operațiuni într-un lot și înregistrări pe pagină. Așadar, „100 de cereri pe minut” nu spune destul despre un endpoint care poate returna sute de mii de rânduri. Pune un plafon pentru dimensiunea paginii și un termen de execuție înainte de a presupune că o singură cotă de frecvență rezolvă problema.
Decide cine consumă cota
Pentru un produs cu organizații și mai multe integrări, stabilește explicit dacă limita se aplică unei chei, unui proiect, întregului client sau unei combinații. Dacă două chei ale aceleiași firme pot consuma fiecare întreaga cotă, crearea de chei suplimentare poate ocoli limita gândită pentru organizație. Pe de altă parte, o singură cotă comună poate face ca un import programat să blocheze aplicația operațională a aceleiași firme. Documentează aceste efecte și testează-le cu un client pilot.
Separă operațiunile după costul real. Citirea unui obiect mic poate avea o limită diferită de generarea unui raport sau de exportul unui fișier. Dacă un endpoint lansează o operațiune lungă, limitează și numărul de lucrări simultane. GitHub documentează limite primare și secundare pentru API-ul său REST; unele endpointuri au limite proprii. Exemplul arată de ce un număr unic, afișat în pagina de prețuri, nu descrie complet comportamentul unei interfețe API.
Ce îi spui clientului când atinge pragul
Răspunsul HTTP 429 trebuie să fie utilizabil de programul clientului. Explică în documentație ce resursă a fost limitată, perioada aplicabilă și dacă există un moment sigur pentru reluare. Dacă trimiți antetul Retry-After, respectă-l și în implementarea serverului: valoarea nu trebuie să promită reluarea când sistemul încă refuză cereri. Pentru limite care se resetează la un moment fix, comunică și această regulă; pentru limite dinamice, evită o precizie pe care sistemul nu o poate garanta.
Recomandările GitHub pentru clienții API cer respectarea Retry-After și, când nu există un astfel de antet, o pauză înainte de o nouă încercare. Ele recomandă și reducerea verificărilor repetate prin webhooks sau cereri condiționale. În documentația propriului SaaS, oferă un exemplu de client care pune cererile în coadă, folosește o pauză progresivă la erori repetate și nu pornește zeci de reîncercări simultan după expirarea unui singur interval.
Reîncercarea unei operațiuni de scriere merită tratată separat. Dacă răspunsul inițial s-a pierdut după ce serverul a creat deja un obiect, retrimiterea oarbă poate crea duplicate. Explică mecanismul de idempotență al produsului, dacă există, și ce operațiuni pot fi repetate în siguranță. Același risc apare la procesarea webhookurilor cu evenimente duplicate, unde clientul nu trebuie să presupună livrare unică.
Testează cota înainte de a o promite în contract
Pregătește trei probe: traficul obișnuit al unei integrări, un vârf scurt justificat de import și o cerere costisitoare repetată. Verifică dacă limita este contabilizată consecvent când aplicația rulează pe mai multe instanțe. Verifică și dacă două organizații diferite rămân izolate: consumul uneia nu trebuie să epuizeze cota celeilalte. Încarcă un client de test până la prag și citește răspunsurile exact cum le-ar vedea echipa sa tehnică.
Publică o pagină cu limitele pe operațiune și cu politica de schimbare. Dacă modifici o cotă existentă, anunță clienții afectați înainte de aplicare și observă erorile 429 după lansare. Pentru clienții care au nevoie de mai mult, definește criterii măsurabile pentru creșterea cotei: volum, ore de vârf, cost și impact asupra celorlalți utilizatori. O excepție nelimitată, acordată fără monitorizare, poate muta problema de la un client la toată platforma.
În jurnalul de audit al unui SaaS B2B, schimbarea cotelor și aprobarea excepțiilor merită consemnate cu autor, moment și motiv. Astfel poți explica de ce integrarea unui client a început să primească 429 după o modificare și poți reveni la configurația anterioară dacă efectul a fost diferit de cel estimat.
Transparență AI: acest conținut poate fi redactat sau structurat cu ajutorul unor instrumente AI și este verificat editorial înainte de publicare. Imaginile generate sau modificate cu AI sunt folosite cu rol ilustrativ.
Întrebări frecvente
Ce înseamnă eroarea HTTP 429 pentru clientul unui API?
Înseamnă că integrarea a trimis prea multe cereri în intervalul sau pentru resursa limitată. Răspunsul trebuie să arate ce limită a fost atinsă și când poate fi reluată cererea, dacă serverul poate furniza acea informație.
Este suficientă o singură limită de cereri pentru toate operațiunile?
De regulă, nu. O citire simplă și un export mare pot consuma resurse diferite; limitele trebuie evaluate și pentru concurență, dimensiunea răspunsului, paginare și costurile serviciilor externe.