# Chyby a kódy

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

## Formát chybovej odpovede

```json
{
  "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:**
```json
{
  "code": "invalid_request",
  "message": "Expired cursor",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

**404 — firma nenájdená:**
```json
{
  "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
```
```json
{
  "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](./rate-limity.md).

**504 — ARES neodpovedal:**
```json
{
  "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.