# Rate limity

## Limity podľa endpointu

| Endpoint | Verejný limit |
|---|---|
| `GET /v1/search` | 100 req/min na IP adresu a trasu |
| `GET /v1/entity/{ico}` | 100 req/min na IP adresu a trasu |
| `GET /v1/health` | bez aplikačného limitu |
| Dopyty do ARES a RÚZ | 60 req/min na IP adresu |

Limit dopytov do ARES a RÚZ sa počíta iba vtedy, keď odpoveď nie je v cache a API sa musí opýtať registra: vyhľadávanie s `country=cz` alebo `both`, detail IČO, ktoré nie je v SK databáze, a doplnenie DIČ z RÚZ pri SK subjekte bez DIČ. Po jeho prekročení vráti CZ dopyt `429` s `details.reason = "upstream"`; SK detail sa vráti bez doplneného DIČ.

Okno pre rate limiting je 60 sekúnd. Limit vynucuje Cloudflare na hranici siete; Worker navyše používa lokálnu ochranu proti krátkym nárazom. Cloudflare počíta limity nezávisle v jednotlivých lokalitách, preto sú hlavičky orientačné a klient sa nemá spoliehať na presne globálny počet zostávajúcich requestov.

## Identita klienta

Klient sa pre účely limitu identifikuje podľa IP adresy a skupiny endpointov. IPv6 adresy sa počítajú za celý prefix `/64`, ktorý zvyčajne patrí jednej sieti. API kľúče v1 nemá; hlavička `X-API-Key` sa ignoruje, pozri [Autentifikácia](./autentifikacia.md).

## Hlavičky odpovedí

Každá odpoveď obsahuje tieto hlavičky:

| Hlavička | Popis |
|---|---|
| `RateLimit-Limit` | Celkový limit pre aktuálne okno |
| `RateLimit-Remaining` | Zostatok requestov v aktuálnom okne |
| `RateLimit-Reset` | Počet sekúnd do resetnutia okna |
| `Retry-After` | Počet sekúnd do ďalšieho povoleného requestu (iba pri `429`) |
| `X-Request-Id` | Unikátne UUID requestu (použite pri hlásení problémov) |
| `X-Response-Time` | Čas spracovania v milisekundách |

## CORS

API posiela `Access-Control-Allow-Origin: *` — requesty z prehliadača sú povolené zo všetkých domén. Preflight OPTIONS requesty sú spracované automaticky.

## Cache-Control

Úspešné odpovede sa môžu ukladať do cache (detail 1 hodinu, detail bez DIČ 5 minút, vyhľadávanie 5 minút, health 30 sekúnd), chybové nikdy. Rovnaké úspešné odpovede ukladá aj Cloudflare v jednotlivých dátových centrách; takú odpoveď označuje hlavička `X-Cache: HIT`. Tabuľka je na stránke [Aktuálnosť dát](./aktualnost-dat.md).

## Pri prekročení limitu

Pri `429 Too Many Requests` skontrolujte hlavičku `Retry-After` a počkajte uvedený počet sekúnd:

```js
const res = await fetch("https://api.subjekt.sk/v1/search?q=slovnaft");
if (res.status === 429) {
  const retryAfter = parseInt(res.headers.get("Retry-After") ?? "60");
  console.log(`Rate limit prekročený, čakám ${retryAfter}s`);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
}
```

Popis chybových kódov nájdete na stránke [Chyby a kódy](./chyby-a-kody.md).