API referencia
Limity požiadaviek API
Verejné limity Subjekt API, hlavičky RateLimit a Retry-After, zdieľané IP adresy a obmedzenia volaní ARES a RÚZ.
Vyskúšaj tento endpoint
{ "stav": "pripravený" }
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.
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.
Pri prekročení limitu
Pri 429 Too Many Requests skontrolujte hlavičku Retry-After a počkajte uvedený počet sekúnd:
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.