# Limity a kvóty

URL: https://postman.slovakodata.com/developers/limity/
Aktualizované: 2026-09-29

Limity volaní podľa balíka, hlavičky RateLimit a RateLimit-Policy, odpoveď 429, veľkosť dokumentu a idempotencia.

<dl class="facts">
  <div class="fact">
    <dt>Veľkosť dokumentu</dt>
    <dd>10<small> MB</small></dd>
  </div>
  <div class="fact">
    <dt>Idempotencia</dt>
    <dd>24<small> h</small></dd>
  </div>
</dl>

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.

**Limity nemajte v kóde napevno — čítajte ich z hlavičiek.** Pri zmene balíka alebo
individuálnej dohode sa limit zmení bez toho, aby ste museli meniť integráciu.

## Kto sa počíta

| Volanie | Limit sa počíta pre |
|---|---|
| Enterprise API (`/api/v1/…`) s API kľúčom alebo prihlásením | celú organizáciu — všetky jej API kľúče a používateľov spolu |
| SAPI-SK (`/sapi/document…`) | každého SAPI klienta zvlášť (`X-Peppol-Participant-Id`) |
| Neoverené volania (registrácia, token endpoint SAPI) | IP adresu |

## 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.

| Skupina | Endpointy |
|---|---|
| `api` | všetko v Enterprise API, čo nepatrí do inej skupiny (odosielanie a čítanie faktúr…) |
| `validate` | `POST /api/v1/documents/validate` — [predbežná validácia](/developers/predbezna-validacia/) |
| `reachability` | `GET /api/v1/participants/:id/reachability` — dostupnosť príjemcu |
| `company-lookup` | `GET /api/v1/invoicing/company/:ico` — údaje odberateľa podľa IČO |
| `invoicing-channel` | `GET /api/v1/invoicing/channel` — kanál doručenia pred vystavením faktúry |
| `sapi` | SAPI-SK `/sapi/document…` |

## Limity podľa balíka

| Skupina | MINI | START | PRO | CORPORATE | ENTERPRISE |
|---|---|---|---|---|---|
| `api` | 20 / s | 50 / s | 100 / s | 100 / s | 200 / s |
| `sapi` (na klienta) | 10 / s | 25 / s | 50 / s | 50 / s | 100 / s |
| `validate` | 10 / min | 30 / min | 60 / min | 150 / min | 300 / min |
| `reachability` | 30 / min | 30 / min | 60 / min | 60 / min | 120 / min |
| `company-lookup` | 30 / min | 30 / min | 30 / min | 30 / min | 30 / min |
| `invoicing-channel` | 30 / min | 30 / min | 60 / min | 60 / min | 120 / min |

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

```http
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
```

| Hlavička | Význam |
|---|---|
| `RateLimit-Policy` | váš limit: skupina, kvóta `q` a okno `w` v sekundách — tu 60 požiadaviek za 60 s |
| `RateLimit` | aktuálny stav: `r` koľko volaní prejde hneď teraz, `t` o koľko sekúnd bude dávka znova celá |
| `X-RateLimit-Limit` | to isté ako `q` |
| `X-RateLimit-Remaining` | to isté ako `r` |
| `X-RateLimit-Reset` | kedy bude dávka znova celá, ako Unix timestamp v sekundách |

`RateLimit` a `RateLimit-Policy` zodpovedajú návrhu štandardu IETF
[RateLimit header fields for HTTP](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/).
`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
HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Policy: "validate";q=60;w=60
RateLimit: "validate";r=0;t=10
```

```json
{
  "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`](/developers/chyby/) 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.

```js
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");
}
```