Chybové kódy a odpovede API

Všetky chybové odpovede majú rovnakú JSON štruktúru bez ohľadu na HTTP status kód.

Formát chybovej odpovede

{
  "code": "invalid_request",
  "message": "Missing q parameter",
  "request_id": "d2be5a4f-ae16-4f95-b75f-8cd6478f4f50"
}

Pole	Popis
`code`	Strojovo čitateľný kód chyby. Podľa neho vetvite logiku.
`message`	Ľudsky čitateľný popis v angličtine. Text sa môže zmeniť, nevetvite podľa neho.
`request_id`	UUID požiadavky, rovnaké ako hlavička `X-Request-Id`. Uveďte ho pri hlásení problému.
`details`	Iba ak chyba nesie doplňujúce údaje, napríklad `{ "reason": "managed" }` pri `429` alebo `{ "reason": "upstream" }`, keď klient prekročil limit dopytov do ARES a RÚZ. Inak pole chýba.

Kódy chýb

HTTP	`code`	Kedy	Čo robiť
400	`invalid_request`	Chýba alebo je neplatný parameter: `q`, `country`, `prefer`, `entity_type`, formát IČO, cursor; pri `country=cz` aj príliš všeobecný dopyt (`details.reason = "cz_query_too_broad"`, viac ako 1 000 zhôd v ARES)	Opravte request podľa dokumentácie endpointu
404	`not_found`	IČO neexistuje v zdroji, alebo neexistuje endpoint	Overte IČO alebo skúste iný `country`
405	`method_not_allowed`	Iná metóda ako `GET`	Používajte iba `GET`
429	`rate_limited`	Prekročený limit požiadaviek, limit dopytov do ARES a RÚZ, alebo limit samotného ARES pri CZ dátach	Počkajte `Retry-After` sekúnd
500	`internal_error`	Neočakávaná chyba servera	Zopakujte neskôr; ak pretrváva, pošlite `request_id`
502	`upstream_unavailable`	ARES vrátil chybu alebo neplatnú odpoveď	Zopakujte neskôr; problém je na strane ARES
504	`timeout`	ARES neodpovedal včas	Zopakujte neskôr s backoffom

Chyby 502 a 504 sa týkajú iba CZ dát. Pri country=both zlyhá celý dopyt, API nevráti len slovenskú časť.

Príklady

400 — expirovaný cursor:

{
  "code": "invalid_request",
  "message": "Expired cursor",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

404 — firma nenájdená:

{
  "code": "not_found",
  "message": "No entity found with ICO 12345670",
  "request_id": "f94251a8-f011-4a98-bf7c-5f1fc45f4abc"
}

429 — rate limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Reset: 42

{
  "code": "rate_limited",
  "message": "Rate limit exceeded",
  "request_id": "c8d9e0f1-2345-6789-bcde-f01234567890",
  "details": { "reason": "managed" }
}

Retry-After je celé číslo v sekundách. Pri opakovaných 429 pridajte exponenciálny backoff. Podrobnosti sú na stránke Rate limity.

504 — ARES neodpovedal:

{
  "code": "timeout",
  "message": "ARES request timed out",
  "request_id": "b7c8d9e0-f123-4567-abcd-e01234567890"
}

Chybové odpovede majú Cache-Control: no-store, takže opakovaný request nikdy nedostane chybu z cache.