# Chybové kódy

URL: https://postman.slovakodata.com/developers/chyby/
Aktualizované: 2026-07-24

Tvar chybovej odpovede SAPI a úplný zoznam kódov s HTTP stavom a opakovateľnosťou.

Každá chyba SAPI má rovnaký tvar a hovorí vám, či má zmysel skúsiť to znova.

```json
{
  "error": {
    "category": "VALIDATION",
    "code": "SAPI-VAL-003",
    "message": "payload is not well-formed XML",
    "correlation_id": "b1f0c2d4-7e19-4a3c-8f52-6d0e91ab7c33",
    "retryable": false,
    "timestamp": "2026-07-13T09:14:22.310Z"
  }
}
```

**Riaďte sa poľom `retryable`.** Neodvodzujte opakovanie z HTTP kódu. Ak je
`retryable: false`, opakovanie nikdy nepomôže — treba opraviť požiadavku. Pri
`true` skúšajte znova s exponenciálne rastúcim odstupom.

Pri hlásení problému nám pošlite `correlation_id`, čas požiadavky a cestu, na
ktorú smerovala. Samotné `correlation_id` sa do našich logov nezapisuje —
vzniká až v odpovedi — takže požiadavku dohľadáme podľa času a cesty.

| Kód | HTTP | Opakovať | Kedy nastane |
|---|---|---|---|
| `SAPI-AUTH-001` | 401 | <span class="status-pill s-danger">nie</span> | Neplatné prihlasovacie údaje alebo token |
| `SAPI-AUTH-002` | 403 | <span class="status-pill s-danger">nie</span> | Peppol identifikátor nepatrí vašej organizácii |
| `SAPI-AUTH-003` | 401 | <span class="status-pill s-danger">nie</span> | Chýba alebo je neplatná hlavička `Authorization` |
| `SAPI-AUTH-004` | 403 | <span class="status-pill s-danger">nie</span> | Účet je pozastavený alebo ešte nie je schválený |
| `SAPI-AUTH-005` | 423 | <span class="status-pill s-danger">nie</span> | Účet dočasne zamknutý po opakovaných neúspešných pokusoch |
| `SAPI-VAL-001` | 400 | <span class="status-pill s-danger">nie</span> | Zlý formát Peppol identifikátora |
| `SAPI-VAL-002` | 400 | <span class="status-pill s-danger">nie</span> | Chýba povinná hlavička alebo telo požiadavky |
| `SAPI-VAL-003` | 400 | <span class="status-pill s-danger">nie</span> | Pole `payload` nie je správne utvorené XML |
| `SAPI-VAL-006` | 400 | <span class="status-pill s-danger">nie</span> | `Idempotency-Key` nie je platné UUID |
| `SAPI-VAL-008` | 400 | <span class="status-pill s-danger">nie</span> | Poškodený `pageToken` |
| `SAPI-VAL-009` | 409 | <span class="status-pill s-danger">nie</span> | Ten istý idempotenčný kľúč s iným telom |
| `SAPI-VAL-010` | 413 | <span class="status-pill s-danger">nie</span> | Dokument je väčší než 10 MB |
| `SAPI-VAL-020` | 400 | <span class="status-pill s-danger">nie</span> | Token stránkovania expiroval (15 minút) |
| `SAPI-PROC-003` | 502 | <span class="status-pill s-ok">áno</span> | Dočasná chyba na našej strane |
| `SAPI-PROC-004` | 402 | <span class="status-pill s-danger">nie</span> | Nedostatočný kredit na odoslanie |
| `SAPI-PERM-002` | 409 | <span class="status-pill s-danger">nie</span> | Doklad s tým istým číslom, dodávateľom a typom (faktúra/dobropis) sa už spracúva alebo bol odoslaný |
| `SAPI-PERM-003` | 404 | <span class="status-pill s-danger">nie</span> | Dokument neexistuje |
| `SAPI-PERM-004` | 410 | <span class="status-pill s-danger">nie</span> | Dokumentu uplynula lehota archivácie |
| `SAPI-TEMP-001` | 503 | <span class="status-pill s-ok">áno</span> | Autentifikačná služba je dočasne nedostupná |
| `SAPI-TEMP-002` | 429 | <span class="status-pill s-ok">áno</span> | Prekročený limit požiadaviek — počkajte podľa `Retry-After` |

### Zlá metóda a neznáma cesta

Zlá HTTP metóda vráti **405** s hlavičkou `Allow`, ktorá menuje správnu — napríklad
`GET` na `/sapi/document/receive/{id}/acknowledge` (endpoint je `POST`) odpovie
`405` a `Allow: POST`. Kód v obálke je `SAPI-VAL-002`.

Neznáma cesta pod `/sapi/` vráti **404** s kódom `SAPI-PERM-003`. Obe odpovede
majú rovnakú chybovú obálku ako tabuľka vyššie.