SAPI-SK — chybové kódy

Všetky chyby na /sapi majú jednotnú obálku so štruktúrovaným objektom error: strojovo čitateľný code a category, explicitný príznak retryable a correlation_id na dohľadanie v logoch a podpore.

Tvar chyby

{
  "error": {
    "category": "VALIDATION",
    "code": "SAPI-VAL-001",
    "message": "Invalid send request",
    "details": [
      { "field": "metadata.documentId", "issue": "Required" }
    ],
    "retryable": false,
    "correlation_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Pole details je voliteľné (napr. validácia na úrovni poľa). category nadobúda hodnoty AUTH, VALIDATION, PROCESSING, TEMPORARY a PERMANENT.

Katalóg kódov

HTTP	Kód	Kategória	Retryable	Význam
401	`SAPI-AUTH-001`	AUTH	nie	Neplatné prihlasovacie údaje klienta.
401	`SAPI-AUTH-002`	AUTH	nie	Access token je neplatný alebo expirovaný.
403	`SAPI-AUTH-003`	AUTH	nie	Klient nemá prístup k danej organizácii / Peppol účastníkovi.
403	`SAPI-AUTH-004`	AUTH	nie	IP adresa nie je na allowliste klienta.
423	`SAPI-AUTH-005`	AUTH	áno	Klient dočasne zamknutý po 5 neúspešných pokusoch (15 min).
400	`SAPI-VAL-001`	VALIDATION	nie	Chybná požiadavka — zlý JSON, chýbajúce pole alebo povinná hlavička (Idempotency-Key, X-Peppol-Participant-Id).
400	`SAPI-VAL-002`	VALIDATION	nie	X-Peppol-Participant-Id sa nezhoduje s metadata.senderParticipantId.
400	`SAPI-VAL-003`	VALIDATION	nie	SHA-256 checksum sa nezhoduje s payloadom.
400	`SAPI-VAL-004`	VALIDATION	nie	Payload prekračuje limit 10 MB.
400	`SAPI-VAL-005`	VALIDATION	nie	Dokument neprešiel Peppol validáciou, alebo číslo koliduje s natívne vystavenou faktúrou (nič sa neodoslalo).
404	`SAPI-VAL-006`	VALIDATION	nie	Dokument neexistuje alebo k nemu nemáte prístup.
409	`SAPI-PROC-001`	PROCESSING	nie	Idempotency-Key už bol použitý s iným telom požiadavky.
422	`SAPI-PROC-002`	PERMANENT	nie	Nedostatok kreditu na odoslanie.
500	`SAPI-PROC-003`	PROCESSING	nie	Interná chyba pri spracovaní.
429	`SAPI-TMP-001`	TEMPORARY	áno	Prekročený rate limit — rešpektujte Retry-After.
502	`SAPI-TMP-002`	TEMPORARY	áno	Peppol sieť dočasne nedostupná — opakujte s exponenciálnym backoffom.

Retry robte iba pri retryable: true (kategórie TEMPORARY a zamknutie SAPI-AUTH-005) a vždy s exponenciálnym backoffom. Pri 429 rešpektujte hlavičku Retry-After.

Odporúčania

Chyby 4xx (okrem 429 a zamknutia 423) neopakujte bez úpravy požiadavky — pole retryable je false. Pri 423 počkajte 15 minút a zopakujte tú istú požiadavku. Pri odosielaní si ukladajte providerDocumentId a používajte stabilný Idempotency-Key, aby ste pri opakovaní predišli duplicitám. correlation_id priložte pri kontakte s podporou.