Limity a kvóty

Veľkosť dokumentu

10 MB

Idempotencia

24 h

Každá organizácia má limit, koľko požiadaviek môže poslať za určitý čas. Limit závisí od vášho balíka a platí zvlášť pre jednotlivé skupiny endpointov. Každá odpoveď vám povie, aký limit máte a koľko z neho zostáva. Po prekročení dostanete 429 s presným časom, kedy môžete skúsiť znova.

Kto sa počíta

Skupiny endpointov

Náročnejšie operácie majú vlastné počítadlo a do všeobecného limitu sa nezapočítavajú — validovanie v cykle vám nezablokuje odosielanie faktúr.

Limity podľa balíka

Ak vám limit nestačí, ozvite sa — dá sa dohodnúť individuálny. Prejaví sa hneď v hlavičkách vašich odpovedí.

Ako sa limit čerpá

Limit nie je okno, ktoré sa naraz vynuluje na začiatku minúty. Kapacita sa dopĺňa priebežne — pri validate s limitom 60 za minútu sa každú sekundu uvoľní jedno volanie.

Navyše máte dávku (burst): niekoľko volaní môžete poslať naraz bez čakania. Pri balíku PRO je to 10 validácií naraz, potom priemerne jedna za sekundu. Nevyčerpaná dávka sa počas pokoja znova doplní.

• rovnomerne rozložené volania v rámci limitu nenarazia nikdy,
• krátku špičku pokryje dávka,
• dlhšia záťaž nad limitom skončí odpoveďou 429.

Hlavičky

RateLimit-Policy: "validate";q=60;w=60
RateLimit: "validate";r=9;t=1
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1790668801

RateLimit a RateLimit-Policy zodpovedajú návrhu štandardu IETF RateLimit header fields for HTTP. X-RateLimit-* posielame pre starších klientov — obsah je rovnaký, stačí čítať jednu dvojicu.

Hlavičky nesie každá odpoveď na požiadavku, ktorá prešla autentifikáciou a kontrolou vstupu — úspešná aj chybová. Nemá ich odpoveď, ktorou požiadavku odmietne autentifikácia (401, 403 pri pozastavenom účte), ani 400/413 z kontroly tvaru požiadavky: tie vznikajú ešte pred započítaním a do limitu sa nepočítajú.

Prekročenie limitu

HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Policy: "validate";q=60;w=60
RateLimit: "validate";r=0;t=10

{
  "statusCode": 429,
  "error": "RATE_LIMIT_EXCEEDED",
  "code": "ERR-429",
  "message": "Too many requests. Retry after 1 seconds.",
  "retry_after": 1
}

Retry-After je presný počet sekúnd do uvoľnenia ďalšieho volania, nie odhad. Rovnakú hodnotu nesie pole retry_after. Neplette si ho s t v hlavičke RateLimit — to je čas, kým sa obnoví celá dávka (v príklade 10 validácií pri balíku PRO). Na SAPI-SK má 429 obálku SAPI-SK s kódom SAPI-TEMP-002 a retryable: true.

Odmietnuté volanie sa nespracuje — faktúra sa neodošle a kredit sa nečerpá. Zopakovať ho je bezpečné.

Odporúčané správanie klienta

1. Pri 429 počkajte Retry-After sekúnd a volanie zopakujte. Neopakujte ho hneď ani v slučke.
2. Pri dávkovom spracovaní sledujte RateLimit — keď r klesá k nule, spomaľte skôr, než príde 429.
3. Paralelné procesy zdieľajú jeden limit organizácie. Rozdeľte si kapacitu alebo posielajte cez jednu frontu.
4. Tempo odvoďte z RateLimit-Policy — q / w je priemerný počet volaní za sekundu.
5. Predbežnú validáciu nepoužívajte na hromadnú kontrolu. Odoslaná faktúra sa validuje sama; predbežná validácia slúži na kontrolu pred odoslaním.

async function volajSLimitom(url, options, pokusy = 5) {
  for (let i = 0; i < pokusy; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    const cakaj = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, cakaj * 1000));
  }
  throw new Error("Limit volaní prekročený aj po opakovaniach");
}