Chyby a limity

Prehľad HTTP kódov, ktoré KROS API vracia, štruktúry chybových odpovedí, rate limitov a odporúčanej retry stratégie — aby ste vedeli spoľahlivo rozlíšiť, ktorý request má zmysel opakovať a ktorý nie.

HTTP kódy

Nasledujúca tabuľka zhŕňa kódy, s ktorými sa pri volaní KROS API stretnete najčastejšie.

Kód	Význam
`202 Accepted`	dáta prijaté na spracovanie; spracovanie beží asynchrónne; odpoveď obsahuje `requestId`
`400 Bad Request`	neplatné alebo chýbajúce dáta; detaily v tele odpovede
`401 Unauthorized`	neplatný alebo chýbajúci autorizačný token
`402 Payment Required`	nedostatočná alebo expirovaná licencia
`405 Method Not Allowed`	endpoint nie je podporovaný alebo je vo vývoji
`409 Conflict`	identický request sa nedá poslať znova do 120 sekúnd od úspešného
`429 Too Many Requests`	prekročený rate limit

202 Accepted

202 Accepted znamená, že dáta boli prijaté na spracovanie — nie že spracovanie uspelo. Skutočný výsledok príde neskôr formou webhooku. Telo odpovede obsahuje requestId, podľa ktorého notifikáciu spárujete s pôvodným nahratím:

{ "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }

202 neznamená úspech

Toto je bežná a nákladná chyba: integrácia, ktorá pri prijatí 202 Accepted označí doklad za úspešne spracovaný, si výsledok domýšľa. Skutočný výsledok spracovania — vrátane prípadného čiastočného zlyhania — sa dozviete až z webhooku, ktorý nesie rovnaké requestId.

400 Bad Request

Telo odpovede obsahuje zoznam konkrétnych problémov, ktoré request zamietli:

{
  "isValid": false,
  "errors": [{
    "documentIndex": 0,
    "propertyPath": "items[0].amount",
    "errorMessage": "Unexpected character encountered while parsing value: a."
  }]
}

documentIndex určuje pozíciu dokladu v rámci vašej dávky — podľa neho request namapujete späť na konkrétny doklad, ktorý ste posielali. propertyPath ukazuje na konkrétne pole, ktoré chybu spôsobilo. Bez tohto rozlíšenia sa chyba nedá priradiť k dokladu, ktorý ju vyvolal, najmä pri dávke s viacerými dokladmi naraz.

Rate limity

Limity sa líšia podľa toho, ktorý povrch voláte. Dátové API má vlastný rozpočet requestov, spúšťacie endpointy Token Brokera vlastný — čísla sa preto nedajú spriemerovať ani nahradiť jednou „bezpečnejšou“ hodnotou.

Dátové API

Okno	Limit
1 sekunda	10 requestov
1 minúta	300 requestov

Obe okná platia súčasne. Desať requestov za sekundu je strop krátkej špičky, nie tempo, ktoré sa dá držať — udržateľná priepustnosť je 5 requestov za sekundu (300 za minútu). Ak by ste posielali plných desať requestov za sekundu nepretržite, minútový rozpočet vyčerpáte po pol minúte a zvyšok minúty dostanete 429.

Rozpočet sa počíta na integračný token, teda na vaše napojenie ako celok — nie na IP adresu a nie na firmu. Ak jedným tokenom obsluhujete viac firiem, delia sa o ten istý rozpočet: dávkové synchronizácie preto rozložte v čase a nespúšťajte ich pre všetky firmy naraz. Do limitu vstupujú iba requesty, ktoré prešli autorizáciou — request s neplatným tokenom skončí na 401 skôr, než sa započíta.

Stav rozpočtu nemusíte odhadovať, API ho posiela v hlavičkách:

Hlavička	Kedy príde	Význam
`x-rate-limit-limit`	pri úspešnej odpovedi	okno, ktorého sa zostatok týka
`x-rate-limit-remaining`	pri úspešnej odpovedi	koľko requestov v tomto okne ešte máte
`x-rate-limit-reset`	pri úspešnej odpovedi	čas resetu okna v sekundách UTC epoch
`retry-after`	pri `429`	počet sekúnd, po ktorých má zmysel skúsiť znova

Limit je strop, nie garantovaná priepustnosť

Ak vám občas prejde viac requestov, než tabuľka uvádza, neberte to ako vyšší limit — plánujte podľa čísel vyššie a spracovanie 429 s odstupom majte v integrácii vždy, aj keď ste na limit zatiaľ nenarazili.

Token Broker

Spúšťací (launch) flow doplnku má vlastné, oveľa nižšie limity — chránia prihlasovanie, nie prenos dát:

Povrch	Limit
spustenie doplnku na strane KROS Gatewaya	10 requestov za minútu na IP adresu
prevzatie launchu na strane vášho doplnku	20 requestov za minútu na IP adresu

Prekročenie vráti 429. Druhé číslo je hodnota, ktorú KROS partnerom odporúča a ktorú má nastavené referenčné riešenie na strane doplnku — ak si spracovanie launchu píšete sami, limit si riadite vy. Pri bežnej práci používateľa sa ani jeden z týchto limitov nedosiahne; narazíte na ne prakticky len pri automatizovanom testovaní, ktoré spúšťa launch v slučke.

Retry stratégia

Na 429 Too Many Requests počkajte toľko sekúnd, koľko uvádza hlavička retry-after; ak v odpovedi nie je, opakujte s exponenciálnym odstupom (exponential backoff). Rovnaký odstup použite na 5xx chyby.
Na 409 Conflict neopakujte request skôr, než uplynie 120-sekundové okno od pôvodného úspešného requestu.
400 Bad Request, 401 Unauthorized a 402 Payment Required nikdy neopakujte — bez zmeny na vašej strane (opravy dát, tokenu alebo licencie) nemôžu uspieť ani na ďalší pokus.
Namiesto slepého opakovania requestu si výsledok radšej overte podľa requestId — najmä pri 202 Accepted, kde reálny výsledok príde webhookom.

Batch limity

Dávka smie obsahovať najviac 100 dokladov na jeden request, rovnako pri nahrávaní aj pri čítaní. Väčšie množstvo rozdeľte na viac requestov a výsledok každého z nich sledujte samostatne podľa jeho vlastného requestId.