Chybové kódyError codes

Tvar chybovej odpovede SAPI a úplný zoznam kódov s HTTP stavom a opakovateľnosťou.The SAPI error response shape and the full list of codes with HTTP status and retryability.

2 min čítania2 min read

#sapi
#chybove kody
#retryable
#correlation_id

#sapi
#error codes
#retryable
#correlation_id

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

{
  "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"
  }
}

Kód	HTTP	Opakovať	Kedy nastane
`SAPI-AUTH-001`	401	nie	Neplatné prihlasovacie údaje alebo token
`SAPI-AUTH-002`	403	nie	Peppol identifikátor nepatrí vašej organizácii
`SAPI-AUTH-003`	401	nie	Chýba alebo je neplatná hlavička `Authorization`
`SAPI-AUTH-004`	403	nie	Účet je pozastavený alebo ešte nie je schválený
`SAPI-AUTH-005`	423	nie	Účet dočasne zamknutý po opakovaných neúspešných pokusoch
`SAPI-VAL-001`	400	nie	Zlý formát Peppol identifikátora
`SAPI-VAL-002`	400	nie	Chýba povinná hlavička alebo telo požiadavky
`SAPI-VAL-003`	400	nie	Pole `payload` nie je správne utvorené XML
`SAPI-VAL-006`	400	nie	`Idempotency-Key` nie je platné UUID
`SAPI-VAL-008`	400	nie	Poškodený `pageToken`
`SAPI-VAL-009`	409	nie	Ten istý idempotenčný kľúč s iným telom
`SAPI-VAL-010`	413	nie	Dokument je väčší než 10 MB
`SAPI-VAL-020`	400	nie	Token stránkovania expiroval (15 minút)
`SAPI-PROC-003`	502	áno	Dočasná chyba na našej strane
`SAPI-PROC-004`	402	nie	Nedostatočný kredit na odoslanie
`SAPI-PERM-002`	409	nie	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	nie	Dokument neexistuje
`SAPI-PERM-004`	410	nie	Dokumentu uplynula lehota archivácie
`SAPI-TEMP-001`	503	áno	Autentifikačná služba je dočasne nedostupná
`SAPI-TEMP-002`	429	áno	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.

Every SAPI error has the same shape and tells you whether retrying makes sense.

{
  "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"
  }
}

Code	HTTP	Retry	When it happens
`SAPI-AUTH-001`	401	no	Invalid credentials or token
`SAPI-AUTH-002`	403	no	The Peppol identifier is not yours
`SAPI-AUTH-003`	401	no	Missing or invalid `Authorization` header
`SAPI-AUTH-004`	403	no	The account is suspended or not yet approved
`SAPI-AUTH-005`	423	no	Account temporarily locked after repeated failures
`SAPI-VAL-001`	400	no	Malformed Peppol identifier
`SAPI-VAL-002`	400	no	A required header or the body is missing
`SAPI-VAL-003`	400	no	The `payload` is not well-formed XML
`SAPI-VAL-006`	400	no	`Idempotency-Key` is not a valid UUID
`SAPI-VAL-008`	400	no	Malformed `pageToken`
`SAPI-VAL-009`	409	no	Same idempotency key, different body
`SAPI-VAL-010`	413	no	The document exceeds 10 MB
`SAPI-VAL-020`	400	no	The page token expired (15 minutes)
`SAPI-PROC-003`	502	yes	A transient error on our side
`SAPI-PROC-004`	402	no	Not enough credit to send
`SAPI-PERM-002`	409	no	A document with the same number, supplier and type (invoice/credit note) is already in progress or was already dispatched
`SAPI-PERM-003`	404	no	The document does not exist
`SAPI-PERM-004`	410	no	The document’s retention period has lapsed
`SAPI-TEMP-001`	503	yes	The authentication service is temporarily down
`SAPI-TEMP-002`	429	yes	Rate limit exceeded — wait as told by `Retry-After`

Wrong method and unknown path

A wrong HTTP method returns 405 with an Allow header naming the right one — e.g. GET on /sapi/document/receive/{id}/acknowledge (the endpoint is POST) answers 405 with Allow: POST. The code in the envelope is SAPI-VAL-002.

An unknown path under /sapi/ returns 404 with code SAPI-PERM-003. Both use the same error envelope as the table above.