Chybové kódy

Všetky chyby majú jednotný tvar JSON s machine-readable code, ľudsky čitateľnou message a voliteľnými details (napr. validačné chyby polí).

Tvar chyby

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Neplatné vstupné údaje",
    "details": [
      { "field": "items", "message": "Musí obsahovať aspoň jednu položku" }
    ]
  }
}

Referencia kódov

HTTP	Kód	Význam / riešenie
400	`VALIDATION_ERROR`	Neplatný vstup. Pozrite details na úroveň poľa.
401	`UNAUTHORIZED`	Chýbajúci/neplatný X-API-Key alebo expirovaná session.
403	`FORBIDDEN`	Kľúč nemá prístup k danej organizácii alebo operácii.
403	`PLAN_LIMIT_REACHED`	Dosiahnutý limit plánu (napr. počet kľúčov).
403	`PLAN_FEATURE_UNAVAILABLE`	Funkcia nie je v aktuálnom pláne.
404	`NOT_FOUND`	Zdroj neexistuje alebo k nemu nemáte prístup.
409	`CONFLICT`	Konflikt (napr. duplicitné číslo faktúry).
409	`PARTNER_CLAIM_COLLISION`	peppol-claim/confirm: pre to isté IČO existuje ďalšia reálna org — firmu nemožno automaticky priradiť. Kontaktujte podporu.
429	`RATE_LIMITED`	Prekročený rate limit — rešpektujte Retry-After.
402	`INSUFFICIENT_CREDIT`	Nedostatok Peppol kreditu pri live odoslaní (POST /agent/peppol/send/*). Doplňte kredit.
402	`SEAT_PAYMENT_FAILED`	Platba za navýšenie zlyhala.
500	`INTERNAL_ERROR`	Chyba na strane servera — skúste neskôr / kontaktujte podporu.

Dva endpointy vracajú neštandardný tvar (nie obálku { "error": { … } }):

POST /agent/peppol/send/* pri nedostatku kreditu vráti 402 s plochým telom { "error": "INSUFFICIENT_CREDIT", "message": "…" } — tu je error reťazec, nie objekt.
POST /agent/organizations/{id}/peppol-claim vracia stav priamo: { "organization_id": "…", "status": "…", "reason": "…" } (napr. status: "collision" s reason: "real_org_exists_for_ico"), nie v obálke error.

Odporúčania

Pri 4xx chybu neopakujte bez úpravy požiadavky. Pri 429 a 5xx použite exponenciálny backoff. Pri vystavovaní faktúr odporúčame ukladať siid vytvoreného dokladu, aby ste predišli duplicitám pri opakovaní.