Prevádzka
Diagnostika chýb
Diagnostiku skrátite na konkrétnu príčinu podľa rozhrania, oprávnenia, firmy a prostredia.
Predpoklady
- Presná HTTP odpoveď a identifikátor požiadavky, ak ho rozhranie vracia.
Diagnostika podľa kódu
HTTP status nestačí: rozhodujte podľa error.code a detailov odpovede. Rovnaký status môže vyžadovať odlišný postup.
Klienti porovnávajú error.code; message je voľný text pre človeka a môže sa zmeniť bez ohlásenia. Úplný zoznam kódov podľa rozhrania je v katalógu nižšie.
| Kód | Najpravdepodobnejšia príčina | Prvý krok |
|---|---|---|
| 401 | Chýbajúci alebo expirovaný token. | Obnovte token a skontrolujte prostredie. |
| 403 | Chýbajúce oprávnenie, nepovolená firma alebo neaktívny prístup. | Porovnajte oprávnenia s dokumentáciou operácie. |
| 404 | Nesprávna cesta alebo dokument pre túto firmu neexistuje. | Skontrolujte cestu a firemný kontext. |
| 409 | Konflikt podľa error.code; napríklad súbežne spracovávaná požiadavka alebo konflikt identity. | Pri súbežnom spracovaní počkajte a overte stav; nemeníte kľúč. Migráciu riešte iba pri potvrdenom konflikte registrácie. |
| 422 | VALIDATION_ERROR: schéma; UBL_VALIDATION_ERROR/VALIDATION_FAILED: fakturačné pravidlá; IDEMPOTENCY_KEY_MISMATCH: zmenené telo pri rovnakom kľúči. | Pri validácii opravte polia alebo pravidlá v details. Pri idempotency konflikte obnovte pôvodné telo alebo overte pôvodnú operáciu; nový kľúč použite iba pre zámerne novú operáciu. Neopakujte 422 naslepo. |
| 429 | Prekročený limit volaní. | Spomaľte a rešpektujte uvedené hlavičky. |
| 502 / 503 alebo timeout | Dočasná nedostupnosť alebo neznámy výsledok; timeout nepotvrdzuje, že operácia neprebehla. | Overte stav. Idempotentnú operáciu opakujte s rovnakým kľúčom a telom, rastúcimi odstupmi a podľa Retry-After. Neidempotentnú pozvánku neopakujte automaticky. |
Katalóg kódov: Enterprise API (/api/v1)
| Kód | HTTP | Význam | Odporúčaný krok |
|---|---|---|---|
| ACTIVATION_UNAVAILABLE | 403 / 409 | Aktiváciu odosielania cez tento odkaz nie je možné dokončiť. | Vyžiadajte od firmy nový aktivačný odkaz alebo kontaktujte podporu s request_id. |
| ADDONS_NOT_READY | 503 | Doplnky ešte nie sú pripravené, objednávku nemožno spracovať. | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu. |
| ADDON_ALREADY_ACTIVE | 409 | Tento doplnok je už aktívny. | Doplnok už nekupujte; zmeňte jeho množstvo v nastaveniach, ak treba. |
| ADDON_NOT_AVAILABLE_FOR_PLAN | 403 | Doplnok nie je dostupný v aktuálnom pláne. | Prejdite na plán, ktorý doplnok podporuje, a zopakujte objednávku. |
| ADDON_ORDER_IN_PROGRESS | 409 | Objednávka doplnku sa už spracúva. | Počkajte na dokončenie objednávky a skontrolujte stav doplnku. |
| ADDON_PAYMENT_METHOD_MISSING | 409 | Na objednanie doplnku chýba platobná metóda. | Pridajte platobnú metódu v Nastavenia → Program a platby a zopakujte objednávku. |
| ADDON_REQUIRED | 409 | Tento doplnok nemáte zapnutý. | Objednajte potrebný doplnok v Nastavenia → Program a platby a zopakujte požiadavku. |
| ALREADY_INACTIVE | 400 | API kľúč je už deaktivovaný. | Nerobte nič, kľúč už nie je aktívny; pre ďalšie volania vytvorte nový kľúč. |
| API_INTERFACE_NOT_AUTHORIZED | 403 | Táto firma alebo kľúč nemá v produkcii povolené požadované API rozhranie. | Požiadajte firmu o schválenie požadovaného rozhrania v súhlase, alebo použite povolené rozhranie. |
| AUTHORIZATION_ALREADY_USED | 409 | Overovací token alebo migračný kód už bol použitý. | Vyžiadajte nový overovací token alebo migračný kód a zopakujte požiadavku. |
| BAD_CONTENT_LENGTH | 400 / 411 | Hlavička Content-Length nie je platné nezáporné celé číslo. | Pošlite správnu hlavičku Content-Length zodpovedajúcu veľkosti tela požiadavky. |
| BAD_REQUEST | 400 / 413 | Požiadavka je neplatná, napríklad telo nie je platný JSON. | Opravte telo alebo parametre požiadavky podľa popisu v message a zopakujte ju. |
| BATCH_ITEM_FAILED | 500 | Položku dávky sa nepodarilo odoslať. | Odošlite túto položku samostatne cez POST /api/v1/documents/send s rovnakým Idempotency-Key. |
| BILLING_IDENTITY_INCOMPLETE | 409 | Firma nemá doplnené úplné firemné a fakturačné údaje potrebné na aktiváciu API. | Požiadajte firmu, aby doplnila chýbajúce údaje v Nastavenia → API, a zopakujte aktiváciu. |
| BOX_DISPATCH_NOT_AVAILABLE | 409 | Položka Schránky nie je prepojená s odosielacím adaptérom Connectora. | Odošlite dokument iným spôsobom (POST /api/v1/documents/send) alebo prepojte položku s Connectorom. |
| BOX_ERROR | 500 | Spracovanie položky Schránky zlyhalo; detail chyby je z bezpečnostných dôvodov skrytý. | Zopakujte akciu neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| BOX_ITEM_NOT_DISPATCHABLE | 409 | Položka Schránky nie je v stave, v ktorom sa dá odoslať. | Načítajte stav položky cez GET /api/v1/box/items/{itemId} a odošlite ju až vo vhodnom stave. |
| BOX_ITEM_STATE_CONFLICT | 409 | Akciu nemožno vykonať, lebo položka Schránky je v inom stave. | Načítajte aktuálny stav položky a zvoľte akciu, ktorá je v ňom povolená. |
| COMPANY_REGISTRY_UNAVAILABLE | 503 | Register firiem je dočasne nedostupný, identitu firmy sa nepodarilo overiť. | Zopakujte tú istú požiadavku s Idempotency-Key o niekoľko minút. |
| COMPANY_VERIFICATION_REQUIRED | 422 | Identitu firmy sa nepodarilo overiť automaticky. | Skontrolujte IČO, DIČ a názov firmy; ak sú správne, kontaktujte podporu s request_id. |
| CONFLICT | 409 | Zdroj už existuje alebo sa požiadavka s týmto Idempotency-Key práve spracúva. | Pri Idempotency-Key počkajte retry_after_seconds a zopakujte s rovnakým kľúčom; inak použite existujúci zdroj. |
| CONFLICT_RETRY_EXHAUSTED | 409 / 400 | Zmena API kľúča sa opakovane dostala do konfliktu s inou súbežnou zmenou. | Zopakujte požiadavku o chvíľu a nevolajte ju súbežne. |
| CONNECTOR_MAILBOX_SUBSCRIPTION | 409 | Odber patrí ku Connector schránke a spravuje ho ePošťák; nemožno ho pozastaviť, upraviť ani zmazať. | Pre vlastné použitie si vytvorte samostatný odber. |
| CONSENT_EXPIRED | 409 | Pozvánka na súhlas už vypršala. | Vytvorte novú pozvánku na súhlas pre túto firmu. |
| CONSENT_NOT_PENDING | 409 | Pozvánka na súhlas už nie je čakajúca, bola vybavená alebo zrušená. | Načítajte stav súhlasu cez GET /api/v1/firms/consent-status a podľa neho pokračujte. |
| CONSENT_REQUIRED | 403 | Aktivácia firmy vyžaduje prijatý súhlas vlastníka alebo správcu s nemenným dôkazom KYC. | Vytvorte pozvánku na súhlas (POST /api/v1/firms/consent-link) a počkajte, kým ju firma prijme. |
| CUSTOMER_ENVIRONMENT_CONFLICT | 409 | Identita firmy je rezervovaná izolovaným testovacím prostredím. | Použite inú firmu alebo kontaktujte podporu s request_id. |
| CUSTOMER_IDENTITY_AMBIGUOUS | 409 | Overenej identite zodpovedá viac firiem na platforme. | Kontaktujte podporu s request_id, aby identitu jednoznačne priradila. |
| CUSTOMER_IDENTITY_MISMATCH | 422 | Overené DIČ firmy sa nezhoduje s údajmi v požiadavke. | Opravte DIČ alebo IČO v požiadavke tak, aby zodpovedali registru, a zopakujte ju. |
| CUSTOMER_REF_ALREADY_EXISTS | 409 | Hodnota customerRef je už priradená inému sandbox účastníkovi. | Použite jedinečný customerRef alebo načítajte existujúceho účastníka. |
| DELIVERY_OWNERSHIP_UNCONFIRMED | 503 | Dokument je uložený, ale nepodarilo sa potvrdiť vlastníctvo automatického doručenia. | Zopakujte požiadavku s rovnakým Idempotency-Key; nevytvárajte nové odoslanie. |
| DOCUMENT_STATUS_CONFLICT | 409 | Dokument je v stave, v ktorom sa požadovaná zmena stavu nedá vykonať. | Načítajte aktuálny stav dokumentu a nastavte iba stav povolený pre prijatý dokument. |
| DOCUMENT_TYPE_NOT_SUPPORTED | 422 | Príjemca je v sieti Peppol, ale tento typ dokumentu neprijíma. | Skontrolujte schopnosti príjemcu (lookup) a pošlite typ dokumentu, ktorý prijíma. |
| DUPLICATE_INVOICE_NUMBER | 409 | Faktúra s týmto číslom už pre firmu existuje. | Upravte existujúci nezaslaný doklad (existingDocument), alebo vystavte opravný doklad s novým číslom. |
| ENDPOINT_RETIRED | 410 | Tento endpoint bol zrušený a už nič nevykoná. | Prejdite na náhradu z fix_hint a docs; požiadavku neopakujte. |
| EVIDENCE_BUNDLE_TOO_LARGE | 413 | Balík dôkazov pre podporu presiahol povolenú veľkosť. | Zúžte rozsah žiadosti (kratšie obdobie alebo menej dokumentov) a zopakujte ju. |
| EXPORT_EXPIRED | 410 | Súbor exportu už nie je dostupný. | Vytvorte nový export cez POST /api/v1/accounting-exports. |
| EXTRACTION_FAILED | 422 | Z dokumentu sa nepodarilo vyčítať údaje faktúry. | Skontrolujte, že ide o čitateľnú faktúru vo formáte PDF alebo obrázka, a nahrajte lepší sken alebo zadajte údaje ručne. |
| FIRM_ACTIVATION_PENDING | 409 | Aktivácia prepojenia s firmou sa ešte dokončuje v rámci oprávnenia alebo fakturácie. | Počkajte niekoľko minút a zopakujte požiadavku alebo skontrolujte stav firmy. |
| FIRM_API_AGREEMENT_CHANGED | 409 | Zmluvné podmienky API sa zmenili od chvíle, keď ich firma videla. | Načítajte aktuálne podmienky, nechajte firmu skontrolovať ich znova a potvrdiť. |
| FIRM_API_PRICING_CHANGED | 409 | Cenové podmienky API sa zmenili od chvíle, keď ich firma videla. | Načítajte aktuálny cenník, nechajte firmu skontrolovať ho znova a potvrdiť. |
| FIRM_COUNT_ABOVE_QUANTITY | 409 | Počet firiem je vyšší než nastavené množstvo doplnku. | Znížte počet firiem alebo zvýšte množstvo doplnku a zopakujte požiadavku. |
| FIRM_LIMIT_REACHED | 403 | Dosiahli ste limit počtu firiem (IČO) vo vašom pláne. | Objednajte doplnok pre ďalšie IČO v Nastavenia → Program a platby. |
| FIRM_NOT_READY | 409 | API možno aktivovať až pre schválenú firmu. | Dokončite registráciu a schválenie firmy a potom zopakujte aktiváciu. |
| FIRM_NOT_REGISTERED | 404 | Firma nie je prepojená s vaším integrátorom: nie je registrovaná v ePošťáku alebo vlastník ešte neprijal vašu ponuku na súhlas. | Vytvorte ponuku cez POST /api/v1/consent-offers, pošlite consentUrl vlastníkovi a po prijatí zopakujte požiadavku. |
| FIRM_SCOPED_KEY_NOT_ALLOWED | 403 | Táto operácia vyžaduje integrátorský kľúč bez obmedzenia na firmu. | Zavolajte endpoint s integrátorským kľúčom, ktorý nie je viazaný na jednu firmu. |
| FIRM_SCOPE_MISMATCH | 403 | API kľúč nie je oprávnený pre túto firmu. | Použite kľúč platný pre túto firmu alebo kľúč integrátora bez obmedzenia na firmu. |
| FORBIDDEN | 403 | Prístup zamietnutý, napríklad firma nie je prepojená s integrátorom alebo je neaktívna. | Skontrolujte firm_id a stav prepojenia cez GET /api/v1/firms. |
| IDEMPOTENCY_KEY_MISMATCH | 422 | Idempotency-Key bol už použitý s iným telom požiadavky. | Pre iné telo požiadavky použite nový Idempotency-Key; pre opakovanie pošlite pôvodné telo. |
| IDEMPOTENCY_KEY_REUSED | 409 / 422 | Idempotency-Key už bol použitý a nedá sa bezpečne zopakovať. | Použite nový Idempotency-Key pre novú operáciu. |
| IDEMPOTENCY_STORE_UNAVAILABLE | 503 | Úložisko idempotencie je dočasne nedostupné, požiadavka sa nespracovala. | Zopakujte požiadavku s rovnakým Idempotency-Key po Retry-After alebo o niekoľko sekúnd. |
| INSUFFICIENT_SCOPE | 403 | Kľúč nemá oprávnenie (scope) potrebné pre túto akciu. | Vytvorte alebo upravte API kľúč tak, aby obsahoval požadovaný scope uvedený v message. |
| INTEGRATOR_AGREEMENT_REQUIRED | 409 | Pred aktiváciou firmy musí byť spracovaná zmluva integrátora. | Dokončite podpis zmluvy integrátora a zopakujte aktiváciu firmy. |
| INTERNAL_ERROR | 500 | Na našej strane nastala neočakávaná chyba. | Pred opakovaním načítajte stav zdroja; ak chyba pretrváva, kontaktujte podporu s request_id. |
| INTERNAL_HANDOFF_AUTHORIZATION_CHANGED | 409 | Oprávnenie účastníka sa počas interného odovzdania zmenilo. | Načítajte aktuálny stav účastníka a začnite operáciu odznova. |
| INTERNAL_PROJECTION_ERROR | 500 | Uložené údaje zákazníka sa nepodarilo bezpečne zobraziť. | Kontaktujte podporu a uveďte request_id. |
| INVALID_CURSOR | 400 | Hodnota cursor nie je platná alebo nepatrí k tomuto zoznamu. | Použite presne hodnotu next_cursor z predchádzajúcej odpovede, alebo začnite bez cursor. |
| INVALID_IDEMPOTENCY_KEY | 400 | Hlavička Idempotency-Key chýba alebo nemá 8 až 128 znakov. | Pošlite Idempotency-Key s dĺžkou 8 až 128 znakov (napr. UUID). |
| INVALID_INVITE | 404 / 409 | Pozývací odkaz už nie je platný. | Vyžiadajte nový pozývací odkaz. |
| INVALID_IP_ALLOWLIST | 400 | Zoznam povolených IP adries obsahuje neplatné položky alebo ich je príliš veľa. | Opravte zoznam podľa message (platné IP/CIDR, najviac povolený počet) a zopakujte požiadavku. |
| INVALID_JSON | 400 | Telo požiadavky nie je platný JSON. | Pošlite platný JSON s hlavičkou Content-Type: application/json. |
| INVALID_NAME | 400 | Názov kľúča je dlhší, než je povolené. | Skráťte názov kľúča na povolenú dĺžku uvedenú v message. |
| INVALID_QUERY | 400 | Parameter status nie je podporovaný stav zákazníka. | Použite niektorú z povolených hodnôt stavu zákazníka. |
| INVALID_REQUEST | 400 | Údaje alebo potvrdenia v požiadavke sú neplatné alebo neúplné. | Skontrolujte povinné údaje a potvrdenia v tele požiadavky a zopakujte ju. |
| INVALID_SCOPES | 400 | Zoznam scope je prázdny alebo obsahuje neznáme hodnoty. | Pošlite aspoň jeden platný scope z dokumentácie. |
| INVALID_WHITE_LABEL_REQUEST | 400 | Požiadavka White Label API nie je platná. | Opravte polia požiadavky podľa chýb v odpovedi a zopakujte ju. |
| IP_NOT_ALLOWED | 403 | Požiadavka prišla z IP adresy, ktorá nie je v zozname povolených adries kľúča. | Volajte API z povolenej IP adresy alebo ju pridajte do zoznamu povolených adries kľúča. |
| LAST_KEY | 409 | Posledný aktívny API kľúč nemožno deaktivovať. | Najprv vytvorte nový kľúč a potom deaktivujte starý. |
| LEGAL_RELEASE_NOT_SIGNABLE | 409 | Aktuálne znenie zmluvných podmienok sa nedá podpísať. | Zopakujte aktiváciu neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| LENGTH_REQUIRED | 411 | Nahrávanie cez multipart vyžaduje hlavičku Content-Length. | Pošlite hlavičku Content-Length (bez chunked prenosu) a zopakujte nahrávanie. |
| LIMIT_REACHED | 400 | Dosiahli ste maximálny počet aktívnych API kľúčov pre tento rozsah firmy. | Deaktivujte nepoužívaný kľúč a potom vytvorte nový. |
| MIGRATION_CODE_NOT_AVAILABLE | 409 | Migračný kód už nie je v SMP dostupný. | Spustite migráciu účastníka znova, aby sa vytvoril nový migračný kód. |
| NOT_FOUND | 404 | Požadovaný zdroj neexistuje alebo k nemu nemáte prístup. | Skontrolujte identifikátor v ceste a to, že patrí vašej firme. |
| ONBOARDING_CONFLICT | 409 | Referencia alebo kľúč už patrí inej požiadavke na onboarding. | Použite jedinečnú referenciu a Idempotency-Key pre každú novú požiadavku. |
| OUTBOUND_OCR_NOT_SUPPORTED | 422 | Rozpoznávanie údajov z dokumentu (OCR) sa pri odosielaní nepodporuje. | Pošlite štruktúrovaný doklad (JSON alebo UBL XML) namiesto PDF alebo obrázka. |
| OWNERSHIP_MISMATCH | 403 | Skenovaná faktúra nepatrí tejto firme. | Nahrajte doklad, ktorého odberateľom alebo dodávateľom je táto firma, alebo zvoľte správnu firmu. |
| PARTICIPANT_ALREADY_MANAGED | 409 | Účastník je už rezervovaný alebo spravovaný iným integrátorom White Label. | Požiadajte o uvoľnenie účastníka u aktuálneho poskytovateľa alebo kontaktujte podporu. |
| PARTICIPANT_ALREADY_REGISTERED | 409 | SMP už účastníka eviduje, preto ho nemožno zaregistrovať ako nového. | Použite tok prichádzajúcej migrácie s migračným kódom od pôvodného poskytovateľa. |
| PARTICIPANT_ALREADY_RELEASED | 409 | Účastník už tohto poskytovateľa White Label opustil. | Načítajte stav účastníka; ďalšia akcia nie je potrebná. |
| PARTICIPANT_OPERATION_NOT_REPLAYABLE | 409 | Operáciu účastníka nemožno v jej aktuálnom stave zopakovať. | Načítajte stav operácie a začnite novú operáciu s novým Idempotency-Key. |
| PARTICIPANT_TRANSITION_CONFLICT | 409 | Účastník má rozbehnutý prechod (registrácia alebo migrácia), ktorý treba najprv dokončiť. | Počkajte na dokončenie prechodu, skontrolujte stav účastníka a zopakujte požiadavku. |
| PARTNER_OFFER_CONFIGURATION_ERROR | 503 | Pozvánku partnera sa nepodarilo vytvoriť pre chybu konfigurácie na našej strane. | Zopakujte neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| PARTNER_OFFER_STATE_CHANGED | 409 | Stav pozvánky partnera sa medzitým zmenil. | Načítajte aktuálny stav pozvánky a rozhodnite sa podľa neho. |
| PARTNER_OFFER_TARGET_MISMATCH | 409 | Cieľová firma sa nezhoduje s firmou, pre ktorú bola pozvánka vytvorená. | Použite IČO alebo DIČ pôvodného príjemcu, alebo vytvorte novú pozvánku pre túto firmu. |
| PARTNER_OFFER_UNAVAILABLE | 403 | Pozvánku partnera nemožno pre tohto partnera použiť. | Skontrolujte povolenia partnera a dostupnosť ponuky; ak nesedí, kontaktujte podporu. |
| PAYLOAD_TOO_LARGE | 413 / 400 | Telo požiadavky presahuje povolenú veľkosť. | Zmenšite telo požiadavky alebo ho rozdeľte do viacerých volaní. |
| PDF_INVOICE_LIMIT_REACHED | 403 | Mesačný limit faktúr z PDF je vyčerpaný. | Dokúpte balík faktúr z PDF alebo počkajte na nový mesiac. |
| PDF_PACK_NOT_YET | 409 | Balík faktúr z PDF sa zatiaľ nedá dokúpiť. | Dokúpte balík až po vyčerpaní mesačného limitu. |
| PEPPOL_BUSINESS_REISSUE_REQUIRES_CONFIRMATION | 409 | Pre dokument už existuje ukončená história doručenia v sieti Peppol. | Overte dôkazy o doručení (stav a MLS); nový odosielací pokus rob iba po potvrdení. |
| PEPPOL_ID_IN_USE | 409 | Identifikátor Peppol je už zaregistrovaný inou firmou. | Skontrolujte identifikátor; ak patrí vašej firme, kontaktujte podporu s request_id. |
| PFS_ACTIVATION_IN_PROGRESS | 409 | Priama aktivácia firmy cez PFS sa práve dokončuje. | Počkajte niekoľko minút a zopakujte požiadavku. |
| PFS_NOTICE_REQUIRED | 409 | Aktivácia vyžaduje doručenie aktuálnych informácií na kontakt z PFS. | Spustite doručenie informácií o ochrane súkromia a po jeho dokončení zopakujte aktiváciu. |
| PFS_PRIVACY_NOTICE_DELIVERY_FAILED | 503 | Oznámenie o ochrane súkromia sa nepodarilo doručiť. | Zopakujte požiadavku neskôr s rovnakým Idempotency-Key. |
| PFS_PRIVACY_NOTICE_DELIVERY_IN_PROGRESS | 409 | Oznámenie o ochrane súkromia sa práve odosiela. | Počkajte chvíľu a zopakujte požiadavku. |
| PRICING_NOT_READY | 409 | Cenník pre túto licenciu ešte nie je pripravený. | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu. |
| PRICING_SNAPSHOT_INVALID | 409 | Kontrola integrity podpísaného snímku cenníka zlyhala. | Kontaktujte podporu s request_id; údaje o cenníku nepoužívajte. |
| PRICING_SNAPSHOT_UNAVAILABLE | 409 | Chýba jednoznačný podpísaný snímok cenníka. | Kontaktujte podporu s request_id, aby doplnila cenník pre túto licenciu. |
| PROVIDER_MIGRATION_ALREADY_ACTIVE | 409 | Pre účastníka už prebieha migrácia k inému poskytovateľovi. | Načítajte stav migrácie a počkajte na jej dokončenie alebo zrušenie. |
| QUEUE_FAILED | 503 | Trvalé odoslanie cez Peppol sa nepodarilo vytvoriť, dokument nebol odoslaný. | Zopakujte odoslanie s rovnakým Idempotency-Key. |
| RECIPIENT_NOT_FOUND | 422 / 409 | Príjemca nie je zaregistrovaný v sieti Peppol. | Skontrolujte identifikátor príjemcu cez lookup a pošlite doklad iným kanálom, ak nie je v sieti. |
| RELEASED_PLATFORM_REACTIVATION_AUTHORIZATION_CHANGED | 409 | Oprávnenie sa počas opätovnej aktivácie uvoľneného účastníka zmenilo. | Načítajte aktuálny stav účastníka a začnite reaktiváciu odznova. |
| RESPONSE_DISPATCH_REJECTED | 502 | Odpoveď na faktúru (Invoice Response) bola odmietnutá pred doručením, nič sa neodoslalo. | Skontrolujte stav dokumentu a zopakujte odpoveď; ak chyba pretrváva, kontaktujte podporu s request_id. |
| RETAINED_ACCOUNT_REVIEW | 409 | Existujúci účet firmy vyžaduje ručnú kontrolu pred aktiváciou API. | Kontaktujte podporu s request_id, aby účet skontrolovala. |
| SANDBOX_CONSENT_UNAVAILABLE | 409 | Testovacia ponuka súhlasu už nie je dostupná. | Načítajte stav ponuky pred opakovaním a v prípade potreby vytvorte novú testovaciu ponuku. |
| SANDBOX_PARTICIPANT_ALREADY_EXISTS | 409 | Syntetická identita účastníka je už rezervovaná inou sandbox operáciou. | Načítajte existujúceho sandbox účastníka alebo použite inú identitu. |
| SAPI-AUTH-005 | 403 / 423 | Kľúč alebo produkčná zmluva nepovoľuje rozhranie SAPI (403), alebo je klient dočasne zablokovaný po opakovaných neúspešných prihláseniach (423). | Pri 403 si nechajte povoliť SAPI v zmluve a nastaveniach kľúča; pri 423 počkajte na odblokovanie a skontrolujte prihlasovacie údaje. |
| SAPI-AUTH-099 | 500 / 503 | Interná chyba pri vydaní, obnovení alebo zrušení tokenu, resp. dočasne nedostupná závislosť overenia (503). | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| SELF_SERVICE_PROVIDER_CHANGE_IN_PROGRESS | 409 | Firma práve sama mení poskytovateľa, operáciu teraz nemožno vykonať. | Počkajte na dokončenie zmeny poskytovateľa a zopakujte požiadavku. |
| SEND_FAILED | 503 | Odoslanie zlyhalo a automatický opakovaný pokus sa nepodarilo zaradiť. | Zopakujte odoslanie s rovnakým Idempotency-Key. |
| SEND_ONLY_DISABLED | 503 | Onboarding iba na odosielanie zatiaľ nie je dostupný. | Skúste to neskôr alebo kontaktujte podporu. |
| SEND_ONLY_INACTIVE | 403 / 409 | Oprávnenie iba na odosielanie nie je aktívne. | Dokončite aktiváciu odosielania pre firmu a zopakujte požiadavku. |
| SEND_ONLY_NOT_AUTHORIZED | 403 | Partner nemá povolený tento onboarding iba na odosielanie. | Požiadajte podporu o povolenie onboardingu iba na odosielanie pre vášho partnera. |
| SEND_ONLY_SCOPE | 403 | Táto operácia nie je dostupná pre službu iba na odosielanie. | Použite iba odosielacie endpointy alebo prejdite na plnú službu. |
| SERVICE_UNAVAILABLE | 503 | Služba alebo jej časť je dočasne nedostupná. | Zopakujte požiadavku po Retry-After; pri return_url skúste bez neho alebo neskôr. |
| SMP_AUTHORIZATION_REJECTED | 422 | SMP odmietol verification token alebo migračný kód. | Pri registrácii použite token vydaný pre DIČ prístupového bodu 2122701339 a DIČ firmy z tela požiadavky (v Overtokene DIC1 a DIC2). Pri migrácii si vyžiadajte od pôvodného poskytovateľa nový platný migračný kód. Potom požiadavku zopakujte. |
| SMP_TEMPORARILY_UNAVAILABLE | 503 | SMP požiadavku neprijal, nič sa nezaregistrovalo. | Zopakujte tú istú požiadavku s rovnakým Idempotency-Key. |
| SUPPLIER_RULE_LIMIT | 409 | Pre tento účtovný program je dosiahnutý maximálny počet pravidiel dodávateľov. | Zmažte nepotrebné pravidlo dodávateľa a potom pridajte nové. |
| TOKEN_REVOKED | 401 | Prístupový token bol zrušený. | Získajte nový prístupový token pomocou API kľúča. |
| UBL_VALIDATION_ERROR | 422 | Vygenerované UBL XML porušuje validačné pravidlo. | Opravte údaje dokumentu podľa pravidla uvedeného v rule a odošlite znova. |
| UNAUTHORIZED | 401 / 400 | Chýba platné overenie alebo je API kľúč neplatný či deaktivovaný. | Pošlite platný API kľúč alebo sa prihláste. |
| UNPROCESSABLE_ENTITY | 422 | Požiadavku nemožno spracovať, napríklad UBL sa po úpravách nepodarilo vygenerovať. | Skontrolujte opravené údaje podľa message a odošlite znova. |
| UNSUPPORTED_MEDIA_TYPE | 415 | Content-Type požiadavky nie je podporovaný. | Pošlite multipart/form-data s jedným poľom document, resp. požadovaný typ z dokumentácie. |
| VALIDATION_ERROR | 422 / 400 | Vstupné údaje nevyhovujú schéme alebo pravidlám. | Opravte polia uvedené v fields a zopakujte požiadavku. |
| VALIDATION_FAILED | 422 | Dokument neprešiel validáciou pravidiel Peppol. | Opravte porušenia pravidiel z fields (rule, path) a odošlite s novým Idempotency-Key. |
| VALIDATION_SERVICE_UNAVAILABLE | 503 | Validačná služba je dočasne nedostupná. | Zopakujte požiadavku po Retry-After s rovnakým Idempotency-Key. |
| VALIDATION_UNAVAILABLE | 503 | Validačná služba je dočasne nedostupná, dokument je zaradený na opakovanie. | Nevytvárajte dokument znova; sledujte jeho stav cez GET /api/v1/documents/{id}. |
| WEBHOOK_DIAGNOSTIC_CAPACITY_EXCEEDED | 429 | Firma má príliš veľa čakajúcich diagnostík webhookov. | Počkajte na dokončenie čakajúcich diagnostík a zopakujte požiadavku po Retry-After. |
| WHITE_LABEL_ACCOUNT_NOT_READY | 409 | Fakturačné a servisné nastavenie White Label ešte nie je pripravené. | Dokončite nastavenie White Label alebo kontaktujte podporu s request_id. |
| WHITE_LABEL_AUTHORIZATION_ENDED | 409 | Oprávnenie účastníka White Label skončilo pred dokončením migrácie. | Načítajte stav účastníka a v prípade potreby začnite novú migráciu. |
| WHITE_LABEL_ENTERPRISE_ORDER_REQUIRED | 409 | Ďalšia produkčná aktivácia vyžaduje podpísanú objednávku Platinum alebo Enterprise. | Podpíšte objednávku Platinum alebo Enterprise; existujúce firmy a export zostávajú dostupné. |
| WHITE_LABEL_FIRM_RELATIONSHIP_CONFLICT | 409 | Firma už má účet na platforme, iný aktívny vzťah s partnerom alebo nezlučiteľnú fakturáciu. | Použite tok pre existujúci účet alebo kontaktujte podporu s request_id. |
| WHITE_LABEL_NOT_ACTIVE | 403 | Vyžaduje sa aktívne produkčné oprávnenie White Label. | Požiadajte o aktiváciu produkčného White Label alebo použite sandbox. |
| WHITE_LABEL_PARTICIPANT_WORKFLOW_REQUIRED | 409 | Firmy White Label sa musia registrovať cez overenie účastníka alebo migračný tok. | Použite API tokov účastníkov White Label namiesto POST /api/v1/firms/assign. |
| WHITE_LABEL_SANDBOX_NOT_ACTIVE | 403 | Vyžaduje sa aktívny sandbox integrátor Enterprise API. | Aktivujte sandbox integrátora alebo použite platný sandbox kľúč. |
Katalóg kódov: SAPI (/sapi/v1)
| Kód | HTTP | Význam | Odporúčaný krok |
|---|---|---|---|
| PEPPOL-PROC-001 | 500 | Overenie účastníka (firmy z hlavičky X-Peppol-Participant-Id) zlyhalo kvôli internej chybe. | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| SAPI-AUTH-001 | 401 | Neplatné client_id alebo client_secret, prípadne demo kľúče použité na produkčnom hoste. | Skontrolujte client_id a client_secret a použite kľúče zodpovedajúce prostrediu (produkcia alebo sandbox). |
| SAPI-AUTH-002 | 401 / 400 | Access token expiroval (401), alebo grant_type nie je client_credentials (400). | Získajte nový token cez /sapi/v1/auth/renew alebo /sapi/v1/auth/token; pri 400 pošlite grant_type=client_credentials. |
| SAPI-AUTH-003 | 401 / 400 | Neplatný access token v hlavičke Authorization (401), alebo v požiadavke na token chýba client_id (400). | Pošlite platný Bearer token; pri vydaní tokenu uveďte client_id. |
| SAPI-AUTH-004 | 400 / 403 | Chýba client_secret alebo je neplatný api_interface (token endpoint SAPI vydáva iba rozhranie sapi). | Doplňte client_secret a nastavte api_interface na sapi (alebo ho vynechajte). |
| SAPI-AUTH-005 | 403 / 423 | Kľúč alebo produkčná zmluva nepovoľuje rozhranie SAPI (403), alebo je klient dočasne zablokovaný po opakovaných neúspešných prihláseniach (423). | Pri 403 si nechajte povoliť SAPI v zmluve a nastaveniach kľúča; pri 423 počkajte na odblokovanie a skontrolujte prihlasovacie údaje. |
| SAPI-AUTH-006 | 403 | Klient je deaktivovaný alebo token nemá požadovaný scope. | Aktivujte klienta v nastaveniach alebo si vyžiadajte token s potrebným scope. |
| SAPI-AUTH-007 | 403 | Požiadavka prišla z IP adresy mimo povoleného zoznamu klienta. | Pridajte IP adresu servera do povoleného zoznamu klienta alebo volajte z povolenej adresy. |
| SAPI-AUTH-008 | 401 / 400 / 403 | Chýba alebo je chybná hlavička Authorization (401), scope je dlhší ako 512 znakov (400), alebo požadovaný scope nie je povolený (403). | Pošlite hlavičku Authorization: Bearer <token> a žiadajte iba scope povolené pre váš kľúč. |
| SAPI-AUTH-009 | 401 | Klient bol zrušený alebo už nie je aktívny. | Vytvorte alebo aktivujte klienta v nastaveniach a získajte nový token. |
| SAPI-AUTH-010 | 400 / 413 | Neplatné JSON telo alebo api_interface pri renew (400), alebo je telo požiadavky príliš veľké (413). | Pošlite platné a malé JSON telo s api_interface=sapi. |
| SAPI-AUTH-011 | 400 | V požiadavke na obnovenie tokenu chýba refresh_token. | Doplňte refresh_token do tela požiadavky na /sapi/v1/auth/renew. |
| SAPI-AUTH-012 | 401 | Refresh token je neplatný alebo expiroval. | Prihláste sa znova cez /sapi/v1/auth/token a použite nový refresh token. |
| SAPI-AUTH-013 | 401 | Refresh token bol zrušený. | Prihláste sa znova cez /sapi/v1/auth/token. |
| SAPI-AUTH-014 | 403 / 400 / 401 | Kľúč nemá oprávnenie pre firmu z X-Peppol-Participant-Id (403), klient už nie je aktívny (401), alebo pri revoke chýba token (400). | Pri 403 si pozrite details[0].issue a opravte prístup firmy alebo nastavenia kľúča; pri 401 aktivujte klienta; pri 400 pošlite token. |
| SAPI-AUTH-015 | 401 / 400 | Väzba klienta na firmu sa zmenila (401), alebo token_type_hint nie je access_token ani refresh_token (400). | Prihláste sa znova cez /sapi/v1/auth/token; pri revoke použite token_type_hint access_token alebo refresh_token. |
| SAPI-AUTH-017 | 401 | Token je neplatný alebo expiroval. | Získajte nový token cez /sapi/v1/auth/token alebo /sapi/v1/auth/renew. |
| SAPI-AUTH-018 | 401 | Token bol zrušený. | Získajte nový token cez /sapi/v1/auth/token. |
| SAPI-AUTH-019 | 503 | Overenie tokenu je dočasne nedostupné. | Zopakujte požiadavku po čase z hlavičky Retry-After. |
| SAPI-AUTH-099 | 500 / 503 | Interná chyba pri vydaní, obnovení alebo zrušení tokenu, resp. dočasne nedostupná závislosť overenia (503). | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| SAPI-DOC-001 | 400 | Hlavička Idempotency-Key chýba alebo nie je platné UUID. | Pošlite hlavičku Idempotency-Key s novým UUID pre každý nový doklad. |
| SAPI-DOC-002 | 400 | Telo požiadavky nie je platné JSON. | Opravte syntax JSON a nastavte Content-Type: application/json. |
| SAPI-DOC-003 | 400 | V tele požiadavky chýba objekt metadata. | Doplňte objekt metadata s povinnými poľami. |
| SAPI-DOC-004 | 400 | V objekte metadata chýbajú povinné polia. | Doplňte polia uvedené v details[] do metadata. |
| SAPI-DOC-005 | 400 | Pole payload chýba alebo je prázdne. | Pošlite UBL XML ako neprázdny reťazec v poli payload. |
| SAPI-DOC-006 | 400 | Pole payloadFormat musí mať hodnotu "XML". | Nastavte payloadFormat na "XML". |
| SAPI-DOC-007 | 403 | senderParticipantId nesedí s firmou z tokenu a hlavičky X-Peppol-Participant-Id. | Nastavte senderParticipantId na Peppol ID firmy, pre ktorú ste autentifikovaní. |
| SAPI-DOC-008 | 400 | Ak je pole checksum uvedené, musí to byť neprázdny reťazec. | Pošlite platný checksum alebo pole vynechajte. |
| SAPI-DOC-009 | 400 | Checksum nezodpovedá obsahu payloadu. | Prepočítajte checksum z nezmeneného payloadu alebo pole vynechajte. |
| SAPI-DOC-010 | 503 | Payload sa nepodarilo uložiť, úložisko je dočasne nedostupné. | Po čase z Retry-After zopakujte nezmenenú požiadavku s rovnakým Idempotency-Key. |
| SAPI-DOC-011 | 503 | Záznam dokladu sa nepodarilo vytvoriť alebo pripraviť odoslanie (persistence_failed alebo tdd_in_flight). | Po čase z Retry-After zopakujte nezmenenú požiadavku s rovnakým Idempotency-Key. |
| SAPI-DOC-012 | 502 / 503 | Prenos cez Peppol zlyhal alebo jeho výsledok treba dohľadať (502), resp. validácia či SMP vyhľadanie príjemcu je dočasne nedostupné (503). | Doklad neposielajte znova s novým kľúčom; pri 503 zopakujte nezmenenú požiadavku s rovnakým Idempotency-Key po Retry-After, pri 502 kontaktujte podporu s providerDocumentId. |
| SAPI-DOC-013 | 400 | receiverParticipantId nie je vo formáte schéma:identifikátor alebo je dlhšie ako 100 znakov (details[].issue too_long). | Zadajte príjemcu ako schéma:identifikátor, napríklad 0245:1234567890, najviac 100 znakov. |
| SAPI-DOC-014 | 202 | Upozornenie v poli messages, nie chyba: príjemca nie je v sieti Peppol, doklad je uložený, ale nedoručí sa. | Doručte doklad príjemcovi inou cestou; ak sa príjemca dodatočne zaregistruje, pošlite to isté UBL XML znova s novým Idempotency-Key. |
| SAPI-DOC-015 | 422 | UBL neprešiel validáciou (XSD, EN 16931, Peppol BIS) alebo príjemca daný typ dokladu či proces neprijíma. | Opravte chyby podľa rule, location a message_sk v details[] a odošlite s novým Idempotency-Key. |
| SAPI-DOC-016 | 413 | Pole payload je väčšie ako 22 MB alebo celé telo požiadavky väčšie ako 25 MB. | Zmenšite doklad alebo väčšie prílohy priložte odkazom cez cac:ExternalReference. |
| SAPI-DOC-017 | 400 | payloadEncoding nie je podporované, podporuje sa iba UTF-8. | Zakódujte payload v UTF-8 a nastavte payloadEncoding na UTF-8. |
| SAPI-DOC-018 | 409 | metadata.documentId už existuje pre odoslaný doklad tohto odosielateľa. | Použite nové documentId; ak ide o opakovanie toho istého dokladu, pošlite nezmenené XML pod pôvodným kľúčom a skontrolujte providerDocumentId v details[]. |
| SAPI-DOC-019 | 400 | Payload nie je platné XML alebo obsahuje nepodporované deklarácie. | Pošlite dobre formované UBL XML bez DOCTYPE a entít. |
| SAPI-DOC-020 | 400 | Parameter limit je mimo povoleného rozsahu. | Nastavte limit na celé číslo v povolenom rozsahu uvedenom v správe chyby. |
| SAPI-DOC-021 | 400 | Parameter status musí byť RECEIVED alebo ACKNOWLEDGED. | Použite status=RECEIVED alebo status=ACKNOWLEDGED. |
| SAPI-DOC-022 | 400 | Parameter pageToken je neplatný. | Použite pageToken z poslednej odpovede bez úprav alebo začnite od prvej strany. |
| SAPI-DOC-023 | 422 | metadata.documentTypeId nesedí s koreňovým elementom UBL. | Nastavte metadata.documentTypeId podľa koreňového elementu UBL (napr. Invoice alebo CreditNote). |
| SAPI-DOC-024 | 409 | Rovnaké UBL XML už bolo odoslané; nový Idempotency-Key ani documentId nový doklad nevytvorí. | Skontrolujte stav pôvodného dokladu cez providerDocumentId v details[]; pri nejasnom výsledku zopakujte pôvodnú požiadavku s rovnakým kľúčom. |
| SAPI-DOC-025 | 422 | EndpointID odosielateľa alebo príjemcu v UBL nesedí s účastníkmi v metadata. | Zosúlaďte EndpointID v UBL so senderParticipantId a receiverParticipantId. |
| SAPI-DOC-026 | 400 | metadata.documentId je dlhšie ako povolených 255 znakov. | Skráťte metadata.documentId na najviac 255 znakov. |
| SAPI-DOC-027 | 422 | Od 1. 1. 2027: IssueDate v UBL sa líši od dátumu odovzdania dokladu (Europe/Bratislava). | Nastavte cbc:IssueDate na dnešný dátum v Europe/Bratislava a odošlite s novým Idempotency-Key. |
| SAPI-DOC-028 | 202 | Upozornenie v poli messages, nie chyba: dátum vystavenia je neskôr ako zákonná lehota (15 dní od dodania, pri súhrnnej faktúre od konca mesiaca). Faktúru odošleme, doručíme a nahlásime Finančnej správe. Do 31. 12. 2026 sa posudzuje cbc:IssueDate, od 1. 1. 2027 deň odovzdania. | Nič neopakujte, doklad je prijatý. Lehotu na vystavenie ďalších faktúr dodržte; za jej porušenie zodpovedá dodávateľ. |
| SAPI-DOC-029 | 422 | Ťarchopis (383) vyžaduje odkaz na predchádzajúcu faktúru (BT-25). | Doplňte do UBL odkaz na pôvodnú faktúru (BillingReference, BT-25). |
| SAPI-DOC-030 | 404 | Prijatý doklad neexistuje alebo nepatrí firme. | Skontrolujte documentId zo zoznamu prijatých dokladov pre správnu firmu. |
| SAPI-DOC-031 | 404 / 503 | Payload prijatého dokladu nie je dostupný (503: uložené XML dočasne chýba, chyba je na našej strane). | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu s documentId a request_id. |
| SAPI-DOC-032 | 500 | Payload prijatého dokladu sa nepodarilo načítať kvôli internej chybe. | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| SAPI-DOC-033 | 409 | DPH obdobie pre dátum zdaniteľného plnenia v doklade už bolo podané. | Opravte dátum zdaniteľného plnenia (details[], pole payload, issue taxable_date) alebo doklad zaradte do otvoreného obdobia. |
| SAPI-DOC-034 | 422 | metadata.documentTypeId nie je typ dokladu, ktorý SAPI prijíma, alebo daný Peppol profil nie je zapnutý na odosielanie. | Použite podporovaný documentTypeId; pri profile_disabled zapnite profil v nastaveniach alebo kontaktujte podporu. |
| SAPI-DOC-035 | 422 | UBL v poli payload sa nedá prečítať ako deklarovaný typ dokladu, takže nevieme overiť odosielateľa a príjemcu. | Pozrite si dôvod v details[].message a skontrolujte koreňový element UBL a metadata.documentTypeId. |
| SAPI-DOC-036 | 422 | Hodnota v UBL sa nedá uložiť: suma presahuje 9 999 999 999,99 alebo údaj presahuje dĺžku poľa. Nič sa neodoslalo. | Opravte hodnotu uvedenú v details[] (field, value) a odošlite s novým Idempotency-Key. |
| SAPI-DOC-040 | 404 | Doklad na potvrdenie (acknowledge) neexistuje alebo nepatrí firme. | Skontrolujte documentId zo zoznamu prijatých dokladov pre správnu firmu. |
| SAPI-DOC-041 | 500 | Potvrdenie prijatého dokladu (acknowledge) zlyhalo kvôli internej chybe. | Zopakujte potvrdenie neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| SAPI-DOC-042 | 422 | Odosielateľ a príjemca sú ten istý účastník, nič sa neodoslalo. | Zadajte ako príjemcu iného účastníka ako odosielateľa. |
| SAPI-DOC-099 | 500 | Pri spracovaní dokladu nastala interná chyba. | Zopakujte požiadavku s rovnakým Idempotency-Key; ak chyba pretrváva, kontaktujte podporu s request_id. |
| SAPI-PROC-001 | 500 | Odoslanie dokladu zlyhalo kvôli internej chybe. | Zopakujte požiadavku s rovnakým Idempotency-Key; ak chyba pretrváva, kontaktujte podporu s request_id. |
| SAPI-PROC-002 | 409 | Idempotency-Key už bol použitý s iným telom požiadavky. | Pre iný doklad použite nový Idempotency-Key; pri opakovaní pošlite pôvodné nezmenené telo. |
| SAPI-PROC-003 | 409 | Požiadavka s týmto Idempotency-Key sa ešte spracováva. | Zopakujte nezmenenú požiadavku s rovnakým Idempotency-Key o chvíľu. |
| SAPI-PROC-004 | 429 | Bola prekročená kvóta odoslaných dokladov pre vašu tarifu. | Prejdite na vyššiu tarifu (upgrade_url v tele odpovede) alebo počkajte do obnovenia kvóty podľa Retry-After. |
| SAPI-PROC-005 | 503 | Výsledok predchádzajúceho odoslania sa ešte dohľadáva. | Zopakujte nezmenenú požiadavku s rovnakým Idempotency-Key po čase z Retry-After. |
| SAPI-TEMP-001 | 503 | Služba je dočasne nedostupná. | Zopakujte požiadavku po čase z hlavičky Retry-After. |
| SAPI-VAL-001 | 400 | Telo požiadavky je neplatné. | Opravte telo podľa špecifikácie endpointu a polí uvedených v details[]. |
| SAPI-VAL-002 | 400 | Chýba povinné pole, napríklad hlavička X-Peppol-Participant-Id. | Doplňte pole uvedené v správe chyby alebo v details[]. |
| SAPI-VAL-003 | 404 | Požadovaný doklad sa nenašiel. | Skontrolujte identifikátor dokladu a že patrí firme, pre ktorú ste autentifikovaní. |
| SAPI-VAL-004 | 400 | X-Peppol-Participant-Id nie je platné Peppol ID alebo ho nevieme priradiť firme. | Pošlite Peppol ID vo formáte schéma:identifikátor, ktoré patrí firme tokenu; príčinu udáva details[0].issue. |
Katalóg kódov: Connector API (/api/v1/connector)
| Kód | HTTP | Význam | Odporúčaný krok |
|---|---|---|---|
| API_INTERFACE_NOT_AUTHORIZED | 403 | Táto firma alebo kľúč nemá v produkcii povolené požadované API rozhranie. | Požiadajte firmu o schválenie požadovaného rozhrania v súhlase, alebo použite povolené rozhranie. |
| AUTOPILOT_IDEMPOTENCY_REQUIRED | 422 | Autopilot príkaz na odoslanie alebo uloženie nemá stabilný idempotentný kľúč. | Pošlite idempotencyKey (alebo hlavičku Idempotency-Key); pre stage môžete použiť aj externalId. |
| AUTOPILOT_IN_PROGRESS | 409 | Rovnaký Autopilot príkaz sa už spracúva. | Zopakujte rovnaký príkaz nezmenený po krátkej pauze. |
| AUTOPILOT_LEGACY_TRANSITION_BLOCKED | 409 | Starší Autopilot príkaz sa nedá bezpečne presunúť do nového stavu. | Skontrolujte stav dokumentu cez GET na Autopilot beh a neposielajte príkaz znova; v prípade potreby kontaktujte podporu s request_id. |
| AUTOPILOT_NEEDS_REPAIR | 422 | Autopilot beh vyžaduje opravu pred pokračovaním. | Prečítajte repairReport, safeFixes a nextActions v odpovedi, opravte podklady a spustite príkaz znova. |
| AUTOPILOT_OUTBOX_IN_PROGRESS | 409 | Prislúchajúca položka Connector outboxu sa medzitým súbežne zmenila. | Zopakujte ten istý Autopilot príkaz. |
| AUTOPILOT_OUTBOX_OWNERSHIP_CONFLICT | 409 | Referencia ERP už patrí inému príkazu Connector outboxu. | Použite pôvodný príkaz pre túto referenciu alebo pošlite novú jedinečnú externalId. |
| AUTOPILOT_REPLAY_MISMATCH | 409 | Rovnaký idempotentný kľúč bol už použitý s iným obsahom príkazu. | Pre zmenený obsah použite nový idempotencyKey, alebo pošlite pôvodný obsah nezmenený. |
| BAD_REQUEST | 400 / 413 | Požiadavka je neplatná, napríklad telo nie je platný JSON. | Opravte telo alebo parametre požiadavky podľa popisu v message a zopakujte ju. |
| CONNECTOR_LEGACY_IDEMPOTENCY_OWNER_UNPROVEN | 409 | Požiadavka s týmto idempotentným kľúčom spred nasadenia môže ešte bežať a jej vlastníka nemožno overiť. | Počkajte a skontrolujte stav dokumentu; nepoužívajte rovnaký kľúč pre nový obsah. |
| CONNECTOR_MAILBOX_SUBSCRIPTION | 409 | Odber patrí ku Connector schránke a spravuje ho ePošťák; nemožno ho pozastaviť, upraviť ani zmazať. | Pre vlastné použitie si vytvorte samostatný odber. |
| CONNECTOR_MAPPER_TEMPLATE_NOT_FOUND | 404 | Mapovacia šablóna so zadaným templateKey neexistuje. | Vytvorte alebo načítajte šablónu v Mapper Studiu a zopakujte požiadavku s rovnakým templateKey. |
| CONNECTOR_OUTBOX_GENERATION_PURGING | 503 | Predchádzajúca generácia dát Connector outboxu sa ešte upratuje. | Zopakujte rovnakú požiadavku o chvíľu. |
| CONNECTOR_OUTBOX_STABLE_REFERENCE_REQUIRED | 422 | Položka Connector outboxu nemá externalId ani idempotencyKey. | Doplňte ku každej položke externalId alebo idempotencyKey. |
| CONNECTOR_OUTBOX_TARGET_STATUS_INVALID | 422 | Cieľový stav generácie Connector outboxu je neplatný. | Použite povolený cieľový stav podľa dokumentácie Connector API. |
| CONNECTOR_PREFLIGHT_RETRY_LATER | 503 | Predkontrola Connectora sa teraz nedokončila. | Zopakujte požiadavku neskôr s rovnakým idempotentným kľúčom. |
| CONNECTOR_REPLAY_ALREADY_ACTIVE | 409 | Pre túto doručenku webhooku už beží aktívny replay. | Počkajte na dokončenie aktívneho replayu a skontrolujte jeho stav. |
| CONNECTOR_REPLAY_CONFLICT | 409 | Replay sa nepodarilo bezpečne rezervovať. | Zopakujte požiadavku o replay po krátkej pauze. |
| CONNECTOR_REPLAY_EVIDENCE_UNAVAILABLE | 409 | Presné podpísané telo pôvodného doručenia webhooku už nie je dostupné. | Replay nie je možný; načítajte aktuálny stav dokumentu cez Connector API. |
| CONNECTOR_REPLAY_NOT_TERMINAL | 409 | Doručenie webhooku, ktoré čaká alebo sa opakuje, sa nedá replayovať. | Počkajte, kým doručenie skončí v konečnom stave, potom replay zopakujte. |
| CONNECTOR_SUCCESSFUL_REPLAY_CONFIRMATION_REQUIRED | 409 | Replay úspešne doručeného webhooku vyžaduje explicitné potvrdenie. | Pošlite confirmSuccessfulReplay=true, ak chcete replay naozaj vykonať. |
| CONNECTOR_TEST_SUITE_ALREADY_ACTIVE | 409 | Diagnostický beh webhookov už prebieha. | Počkajte na dokončenie aktívneho behu a sledujte jeho stav. |
| CONSENT_GENERATION_CHANGED | 409 | Generácia súhlasu pre Connector webhook sa zmenila. | Znova načítajte údaje o súhlase firmy a požiadavku zopakujte. |
| CONSENT_REVOKED | 403 | Súhlas firmy pre Connector webhook už nie je aktívny. | Požiadajte firmu o obnovenie súhlasu v nastaveniach Connectora. |
| CSV_HEADER_LIMIT_EXCEEDED | 422 | CSV vzorka má viac stĺpcov, ako je povolené. | Znížte počet stĺpcov v CSV a nahrajte vzorku znova. |
| CSV_HEADER_TOO_LARGE | 422 | Hlavička CSV vzorky je príliš veľká. | Skráťte názvy stĺpcov v CSV a nahrajte vzorku znova. |
| CSV_ROW_LIMIT_EXCEEDED | 422 | CSV vzorka má viac riadkov, ako je povolené. | Nahrajte menšiu vzorku s menším počtom riadkov. |
| CSV_ROW_TOO_LARGE | 422 | Riadok CSV vzorky je príliš veľký. | Skráťte hodnoty vo veľkých riadkoch a nahrajte vzorku znova. |
| CSV_ROW_WIDTH_MISMATCH | 422 | Riadky CSV vzorky nemajú rovnaké stĺpce. | Zjednoťte stĺpce vo všetkých riadkoch CSV a nahrajte vzorku znova. |
| CUSTOMER_NOT_READY | 409 / 403 | Zákazník (customerRef) nie je pripravený na odosielanie dokladov cez Connector alebo ho kľúč API neoprávňuje. | Použite customerRef, ktorý operátor schválil a prepojil a ktorý je povolený pre tento kľúč API. |
| CUSTOMER_REF_ALREADY_IN_USE | 409 | Hodnota customerRef sa už používa pre inú spravovanú firmu. | Zvoľte pre firmu iný jedinečný customerRef. |
| CUSTOMER_REF_CHANGED | 409 | Hodnota customerRef sa zmenila pred vykonaním dokumentu. | Zopakujte príkaz s aktuálnym customerRef firmy. |
| CUSTOMER_REF_LOCKED | 409 | customerRef sa nedá zmeniť po prvom pripravenom alebo odoslanom dokumente. | Ponechajte pôvodný customerRef; pre inú identitu založte novú firmu. |
| DELIVERY_TEMPORARILY_UNAVAILABLE | 503 | Connector teraz nedokáže požiadavku dokončiť. | Zopakujte tú istú požiadavku neskôr (rešpektujte Retry-After); pri pretrvávaní kontaktujte podporu s request_id. |
| DEPTH_LIMIT_EXCEEDED | 422 | Vzorka presahuje povolenú hĺbku vnorenia. | Zjednodušte štruktúru vzorky a nahrajte ju znova. |
| DOCUMENT_CANDIDATE_INVALID | 422 | Výber dokladov vo vzorke je neplatný alebo presahuje povolený počet. | Upravte selektor dokladov tak, aby vybral povolený počet dokladov. |
| DOCUMENT_CONTENT_INVALID | 415 | Obsah dokumentu nezodpovedá deklarovanému formátu. | Nahrajte súbor, ktorého obsah zodpovedá jeho prípone a typu. |
| DOCUMENT_DELIVERY_FAILED | 502 | Autopilot doklad bol prijatý, ale doručenie cez Peppol zlyhalo (lastError behu). | Pozrite detail cez GET /api/v1/connector/documents/{id}; po oprave pošlite doklad ako nový beh s novým externalId. |
| DOCUMENT_INVALID | 422 / 400 / 413 | Telo požiadavky alebo doklad je neplatný (zlý JSON, chýbajúce pole alebo príliš veľké telo). | Opravte pole uvedené v odpovedi (field, nextAction) a zopakujte požiadavku. |
| DOCUMENT_KEY_INVALID | 422 | Kľúč dokladu vo vzorke musí byť jedna neprázdna skalárna hodnota. | Upravte selektor kľúča dokladu tak, aby vybral jednu neprázdnu hodnotu. |
| DOCUMENT_TYPE_NOT_SUPPORTED | 422 | Príjemca je v sieti Peppol, ale tento typ dokumentu neprijíma. | Skontrolujte schopnosti príjemcu (lookup) a pošlite typ dokumentu, ktorý prijíma. |
| FIRM_SCOPED_KEY_NOT_ALLOWED | 403 | Táto operácia vyžaduje integrátorský kľúč bez obmedzenia na firmu. | Zavolajte endpoint s integrátorským kľúčom, ktorý nie je viazaný na jednu firmu. |
| GOLDEN_CONFLICT | 409 | Inbound vzorka sa medzitým zmenila. | Obnovte profil a zopakujte akciu. |
| GOLDEN_DOCUMENT_INVALID | 422 | Golden kanonický doklad nie je platný. | Opravte chyby kanonického dokladu uvedené v odpovedi a odošlite ho znova. |
| GOLDEN_IMMUTABLE | 409 | Potvrdený inbound pár je nemenný. | Nahrajte novú vzorku namiesto úpravy potvrdenej. |
| GOLDEN_SOURCE_INCOMPLETE | 422 | Zdrojová vzorka je pre golden kontrolu neúplná. | Doplňte chýbajúce údaje vo zdrojovej vzorke alebo nahrajte úplnejšiu. |
| IDEMPOTENCY_CONFLICT | 409 | Idempotentný kľúč už bol použitý s iným obsahom dokladu. | Pre zmenený doklad použite nový idempotencyKey, alebo pošlite pôvodný obsah nezmenený. |
| IDEMPOTENCY_KEY_MISMATCH | 422 | Idempotency-Key bol už použitý s iným telom požiadavky. | Pre iné telo požiadavky použite nový Idempotency-Key; pre opakovanie pošlite pôvodné telo. |
| IDEMPOTENCY_KEY_REUSED | 409 / 422 | Idempotency-Key už bol použitý a nedá sa bezpečne zopakovať. | Použite nový Idempotency-Key pre novú operáciu. |
| INCOMPLETE_PROVENANCE | 409 | Pôvod doručenia Connector webhooku je neúplný. | Doručenie nemožno replayovať; načítajte stav dokumentu cez Connector API. |
| INSUFFICIENT_SCOPE | 403 | Kľúč nemá oprávnenie (scope) potrebné pre túto akciu. | Vytvorte alebo upravte API kľúč tak, aby obsahoval požadovaný scope uvedený v message. |
| INTEGRATOR_INACTIVE | 403 | Účet integrátora nie je aktívny. | Kontaktujte podporu ePošťák a overte stav účtu integrátora. |
| INTERNAL_ERROR | 500 | Na našej strane nastala neočakávaná chyba. | Pred opakovaním načítajte stav zdroja; ak chyba pretrváva, kontaktujte podporu s request_id. |
| INVALID_CURSOR | 400 | Hodnota cursor nie je platná alebo nepatrí k tomuto zoznamu. | Použite presne hodnotu next_cursor z predchádzajúcej odpovede, alebo začnite bez cursor. |
| INVALID_LIMIT | 422 | Limit pri profilovaní vzorky musí byť kladné celé číslo. | Zadajte kladné celé číslo pre daný limit. |
| INVALID_MULTIPART | 400 | Telo požiadavky nie je platné multipart/form-data. | Pošlite súbor ako multipart/form-data so správnymi poľami. |
| INVALID_SELECTOR | 422 | Selektor dokladov vo vzorke je neplatný. | Opravte syntax selektora a zopakujte požiadavku. |
| INVALID_SOURCE | 422 | Zdrojová vzorka obsahuje nepodporovanú alebo neplatnú štruktúru. | Odstráňte neplatné hodnoty (nekonečné čísla, cyklické odkazy, nie-JSON hodnoty) a nahrajte vzorku znova. |
| IP_NOT_ALLOWED | 403 | Požiadavka prišla z IP adresy, ktorá nie je v zozname povolených adries kľúča. | Volajte API z povolenej IP adresy alebo ju pridajte do zoznamu povolených adries kľúča. |
| MALWARE_SCANNER_UNAVAILABLE | 503 | Kontrola bezpečnosti dokumentu je dočasne nedostupná. | Zopakujte nahranie neskôr. |
| NODE_LIMIT_EXCEEDED | 422 | Vzorka obsahuje viac uzlov, ako je povolené. | Zmenšite alebo zjednodušte vzorku a nahrajte ju znova. |
| NOT_FOUND | 404 | Požadovaný zdroj neexistuje alebo k nemu nemáte prístup. | Skontrolujte identifikátor v ceste a to, že patrí vašej firme. |
| OCR_EXTRACTION_FAILED | 503 | Doklad sa nepodarilo bezpečne vyťažiť pomocou OCR. | Zopakujte nahranie neskôr alebo nahrajte čitateľnejší súbor. |
| OCR_EXTRACTION_INTEGRITY_MISMATCH | 409 | OCR extrakcia nezodpovedá pôvodnej vzorke. | Nahrajte vzorku znova. |
| OCR_EXTRACTION_VERSION_MISMATCH | 409 | OCR vzorka používa inú verziu extrakcie. | Nahrajte vzorku znova, aby sa vyťažila aktuálnou verziou. |
| OCR_PROCESSING_NOT_APPROVED | 503 | Externé OCR spracovanie nie je v tomto prostredí schválené. | Použite JSON, CSV alebo XML vzorku, alebo kontaktujte podporu. |
| PAYLOAD_TOO_LARGE | 413 / 400 | Telo požiadavky presahuje povolenú veľkosť. | Zmenšite telo požiadavky alebo ho rozdeľte do viacerých volaní. |
| PROFILE_KEY_CONFLICT | 409 | Kľúč mapovacieho profilu sa už používa. | Zvoľte iný kľúč profilu. |
| PROPOSAL_CONFLICT | 409 | Návrh mapovania sa medzitým zmenil alebo vypršal. | Obnovte profil a skúste znova. |
| PROPOSAL_FAILED | 422 | Zo zvolených vzoriek sa nepodarilo pripraviť jednoznačný návrh mapovania. | Pridajte alebo vyberte reprezentatívnejšie vzorky a skúste znova. |
| RATE_LIMITED | 429 | Počas jednej hodiny možno spustiť najviac päť diagnostických behov. | Počkajte a spustite diagnostiku neskôr. |
| RECIPIENT_AMBIGUOUS | 409 | Príjemca sa nedá jednoznačne určiť. | Upresnite príjemcu (napr. identifikátor Peppol) a zopakujte požiadavku. |
| RECIPIENT_LOOKUP_UNAVAILABLE | 503 | Vyhľadanie príjemcu v sieti Peppol je dočasne nedostupné. | Zopakujte požiadavku neskôr s rovnakým idempotentným kľúčom. |
| RECIPIENT_NOT_FOUND | 422 / 409 | Príjemca nie je zaregistrovaný v sieti Peppol. | Skontrolujte identifikátor príjemcu cez lookup a pošlite doklad iným kanálom, ak nie je v sieti. |
| RECIPIENT_NOT_REACHABLE | 422 | Príjemca nie je dosiahnuteľný v sieti Peppol. | Skontrolujte identifikátor príjemcu alebo použite iný spôsob doručenia. |
| REVISION_CONFLICT | 409 | Mapovací profil sa medzitým zmenil. | Obnovte profil a skúste znova. |
| REVISION_NOT_EVALUATABLE | 409 | Vyhodnotiť možno iba aktuálnu inbound kandidátsku revíziu. | Obnovte profil a vyhodnoťte aktuálnu kandidátsku revíziu. |
| SAMPLE_INVALID | 422 | Vzorku alebo mapovaciu špecifikáciu sa nepodarilo bezpečne spracovať. | Skontrolujte, či je vzorka platný súbor v podporovanom formáte, a nahrajte ju znova. |
| SAMPLE_LIMIT_REACHED | 409 | Profil môže obsahovať najviac 10 aktívnych vzoriek. | Odstráňte nepotrebnú vzorku a pridajte novú. |
| SAMPLE_NOT_IN_REVISION | 409 | Vzorka nepatrí do tejto revízie. | Počkajte na nový návrh mapovania alebo obnovte profil. |
| SAMPLE_SET_CONFLICT | 409 | Množina vzoriek sa medzitým zmenila. | Obnovte profil a skúste znova. |
| SAMPLE_TYPE_UNSUPPORTED | 422 | Typ vzorky nie je podporovaný. | Nahrajte vzorku vo formáte JSON, CSV, XML, PDF, JPG, PNG alebo WebP. |
| SAMPLE_UNAVAILABLE | 410 | Zvolená vzorka už nie je dostupná. | Nahrajte vzorku znova. |
| SCALAR_TOO_LARGE | 422 | Hodnota vo vzorke je väčšia, ako je povolené. | Skráťte veľké hodnoty vo vzorke a nahrajte ju znova. |
| SELECTOR_NO_MATCH | 422 | Selektor kľúča dokladu nenašiel žiadneho kandidáta. | Upravte selektor tak, aby zodpovedal štruktúre vzorky. |
| SOURCE_TOO_LARGE | 422 | Profilovaná zdrojová vzorka je väčšia, ako je povolené. | Nahrajte menšiu vzorku. |
| STAGED_CONTENT_EXPIRED | 422 | Uložený obsah pripraveného dokumentu po 14 dňoch vypršal a bol odstránený, dokument sa už nedá odoslať. | Tento documentId neopakujte. Pošlite dokument znova ako nový pripravený dokument s novým externalId. |
| STRUCTURAL_KEY_TOO_LARGE | 422 | Názov kľúča vo vzorke je dlhší, ako je povolené. | Skráťte príliš dlhé kľúče vo vzorke a nahrajte ju znova. |
| UNAUTHORIZED | 401 / 400 | Chýba platné overenie alebo je API kľúč neplatný či deaktivovaný. | Pošlite platný API kľúč alebo sa prihláste. |
| UNSAFE_DOCUMENT | 422 | Dokument neprešiel kontrolou na škodlivý kód. | Nahrajte iný, bezpečný súbor. |
| UNSUPPORTED_MEDIA_TYPE | 415 | Content-Type požiadavky nie je podporovaný. | Pošlite multipart/form-data s jedným poľom document, resp. požadovaný typ z dokumentácie. |
| VALIDATION_ERROR | 422 / 400 | Vstupné údaje nevyhovujú schéme alebo pravidlám. | Opravte polia uvedené v fields a zopakujte požiadavku. |
| VALIDATION_FAILED | 422 | Dokument neprešiel validáciou pravidiel Peppol. | Opravte porušenia pravidiel z fields (rule, path) a odošlite s novým Idempotency-Key. |
| VALIDATION_SERVICE_UNAVAILABLE | 503 | Validačná služba je dočasne nedostupná. | Zopakujte požiadavku po Retry-After s rovnakým Idempotency-Key. |
| VALIDATOR_VERSION_REQUIRED | 503 | Peppol validátor nemá nastavenú presnú verziu, revíziu nemožno schváliť. | Zopakujte neskôr; pri pretrvávaní kontaktujte podporu s request_id. |
| WEBHOOK_INACTIVE | 403 | Oprávnenie Connector webhooku už nie je aktívne. | Znova aktivujte webhook alebo súhlas firmy v nastaveniach Connectora. |
| WRONG_CONTRACT | 404 | Doručenie webhooku sa nenašlo pre zmluvu Connector. | Skontrolujte identifikátor doručenia a použite webhook s kontraktom CONNECTOR_V1. |
| WRONG_INTEGRATOR | 404 | Doručenie webhooku sa nenašlo pre tohto integrátora. | Skontrolujte identifikátor doručenia a použitý API kľúč. |
| XML_ROOT_AMBIGUOUS | 422 | XML vzorka musí mať jeden koreňový element. | Upravte XML tak, aby mal práve jeden koreňový element. |
| XML_ROOT_INVALID | 422 | XML vzorka nemá jednoznačný koreňový element. | Nahrajte platné XML s jedným koreňovým elementom. |
Katalóg kódov: Managed API v2 (/api/v2)
| Kód | HTTP | Význam | Odporúčaný krok |
|---|---|---|---|
| CUSTOMER_AUTHORIZATION_REQUIRED | 400 | Vytvorenie White Label zákazníka vyžaduje vzťah „represented“ a údaje o súhlase zákazníka (customerAuthorization). | Pošlite relationship „represented“ a vyplnené pole customerAuthorization. |
| INTERNAL_PROJECTION_ERROR | 500 | Uložené údaje zákazníka sa nepodarilo bezpečne zobraziť. | Kontaktujte podporu a uveďte request_id. |
| INVALID_QUERY | 400 | Parameter status nie je podporovaný stav zákazníka. | Použite niektorú z povolených hodnôt stavu zákazníka. |
| UNAUTHORIZED | 401 / 400 | Chýba platné overenie alebo je API kľúč neplatný či deaktivovaný. | Pošlite platný API kľúč alebo sa prihláste. |
| WHITE_LABEL_CUSTOMERS_NOT_AUTHORIZED | 403 | Vyžaduje sa aktivácia White Label sandboxu v Enterprise API. | Aktivujte White Label sandbox alebo kontaktujte podporu. |
| WHITE_LABEL_CUSTOMER_ACCOUNT_INVALID | 409 | Produkčný účet nie je nastavený na spravovaných zákazníkov. | Kontaktujte podporu a požiadajte o nastavenie účtu. |
| WHITE_LABEL_CUSTOMER_ACCOUNT_NOT_READY | 409 | Účet White Label zákazníka ešte nie je aktívny. | Počkajte na aktiváciu účtu a zopakujte požiadavku. |
| activation_dependency_unavailable | 503 | Závislá služba potrebná na aktiváciu zákazníka je dočasne nedostupná. | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| artifact_integrity_failed | 500 | Uložený súbor dokumentu sa nepodarilo bezpečne vrátiť, lebo neprešiel kontrolou integrity. | Zopakujte sťahovanie; ak chyba pretrváva, kontaktujte podporu s request_id. |
| artifact_not_available | 409 | Požadovaný súbor dokumentu zatiaľ nie je dostupný. | Skúste to znova neskôr, keď bude dokument spracovaný. |
| attachment_not_found | 404 | Príloha dokumentu neexistuje. | Skontrolujte identifikátor prílohy v detaile dokumentu. |
| authentication_unavailable | 503 | Overenie API kľúča je dočasne nedostupné. | Zopakujte požiadavku neskôr; ak chyba pretrváva, kontaktujte podporu s request_id. |
| concurrent_transition | 409 | Dokument práve mení stav iná požiadavka. | Zopakujte požiadavku po krátkej chvíli a znova načítajte dokument. |
| concurrent_update | 409 / 400 | Záznam zároveň upravila iná požiadavka. | Znova načítajte záznam a zopakujte zmenu. |
| content_incomplete | 409 | Obsah dokumentu je neúplný, preto sa operácia nedá vykonať. | Doplňte chýbajúce údaje dokumentu a zopakujte požiadavku. |
| content_length_required | 400 | Požiadavka neobsahuje hlavičku Content-Length. | Pošlite telo s hlavičkou Content-Length (bez chunked prenosu). |
| corrupt_customer | 500 | Uložené údaje zákazníka sú nekonzistentné. | Kontaktujte podporu a uveďte request_id. |
| corrupt_document | 500 | Uložené údaje dokumentu sú nekonzistentné. | Kontaktujte podporu a uveďte request_id. |
| customer_activation_unavailable | 409 | Zákazníka sa momentálne nedá aktivovať. | Skontrolujte stav zákazníka a zopakujte aktiváciu; ak nepomôže, kontaktujte podporu. |
| customer_changed | 409 | Zákazník sa počas vytvárania dokumentu zmenil. | Znova načítajte zákazníka a zopakujte vytvorenie dokumentu. |
| customer_environment_conflict | 409 | Prostredie zákazníka (sandbox/produkcia) nesedí s prostredím API kľúča. | Použite API kľúč zo zodpovedajúceho prostredia. |
| customer_identity_ambiguous | 422 | Identita zákazníka sa nedá jednoznačne určiť. | Upresnite identifikátory zákazníka (IČO, DIČ, Peppol ID) a zopakujte požiadavku. |
| customer_identity_mismatch | 422 | Údaje zákazníka nesedia s existujúcim záznamom. | Opravte identifikátory zákazníka alebo použite správnu referenciu customer_ref. |
| customer_inactive | 422 | Zákazník nie je aktívny. | Dokončite aktiváciu zákazníka alebo použite aktívneho zákazníka. |
| customer_not_found | 404 / 422 | Zákazník neexistuje. | Skontrolujte identifikátor alebo customer_ref a zákazníka prípadne najprv vytvorte. |
| customer_ref_conflict | 409 | Referencia customer_ref už patrí inému zákazníkovi. | Použite inú, jedinečnú hodnotu customer_ref. |
| customer_ref_invalid | 400 | Hodnota customer_ref má neplatný formát. | Použite 1 až 128 znakov: písmená, číslice, bodku, podčiarkovník alebo pomlčku. |
| customer_relationship_invalid | 409 | Zákazník už nezodpovedá organizácii účtu API. | Skontrolujte vzťah zákazníka a účtu API; ak nesedí, kontaktujte podporu. |
| delivery_not_found | 404 | Doručenie webhooku neexistuje. | Skontrolujte identifikátor doručenia v zozname doručení webhooku. |
| delivery_outcome_conflict | 409 | Výsledok doručenia dokumentu je v konflikte s už uloženým stavom. | Znova načítajte dokument a skontrolujte jeho aktuálny stav. |
| document_not_found | 404 / 500 | Dokument neexistuje alebo k nemu nemáte prístup. | Skontrolujte identifikátor dokumentu a zákazníka. |
| external_id_conflict | 409 | Externé ID dokumentu už použil iný dokument. | Použite jedinečné externé ID alebo načítajte existujúci dokument. |
| external_id_invalid | 400 | Externé ID dokumentu má neplatný formát. | Skontrolujte dĺžku a znaky externého ID (bez riadiacich znakov). |
| idempotency_conflict | 409 | Kľúč idempotencie už bol použitý s inou požiadavkou. | Pre inú požiadavku použite nový Idempotency-Key. |
| idempotency_key_conflict | 409 | Kľúč idempotencie už bol použitý s iným obsahom dokumentu. | Zopakujte rovnakú požiadavku alebo použite nový Idempotency-Key. |
| idempotency_key_invalid | 400 | Hlavička Idempotency-Key má neplatný formát. | Pošlite platný Idempotency-Key (krátky text bez riadiacich znakov). |
| idempotency_key_required | 400 | Vytvorenie dokumentu vyžaduje hlavičku Idempotency-Key. | Pridajte hlavičku Idempotency-Key a zopakujte požiadavku. |
| insufficient_scope | 403 | API kľúč nemá potrebný rozsah (scope) na túto operáciu. | Použite kľúč s potrebným rozsahom alebo ho upravte v portáli. |
| internal_error | 500 | Požiadavku sa nepodarilo dokončiť kvôli internej chybe. | Zopakujte požiadavku; ak chyba pretrváva, kontaktujte podporu s request_id. |
| internal_projection_error | 500 | Uložené údaje sa nepodarilo bezpečne zobraziť. | Kontaktujte podporu a uveďte request_id. |
| invalid_api_key | 401 | API kľúč je neplatný alebo chýba. | Pošlite platný kľúč v hlavičke Authorization: Bearer. |
| invalid_authorization | 401 | Hlavička Authorization má neplatný formát. | Pošlite hlavičku v tvare Authorization: Bearer ep_<prostredie>_<kľúč>. |
| invalid_content_length | 400 | Hlavička Content-Length má neplatnú hodnotu. | Pošlite správnu hodnotu Content-Length zodpovedajúcu veľkosti tela. |
| invalid_credential_randomness | 500 | Vygenerovaný prihlasovací údaj nespĺňa požiadavky na náhodnosť. | Zopakujte vytvorenie kľúča; ak chyba pretrváva, kontaktujte podporu. |
| invalid_cursor | 400 | Kurzor stránkovania je neplatný. | Použite kurzor z poslednej odpovede alebo začnite od prvej stránky. |
| invalid_json | 400 | Telo požiadavky neobsahuje platný JSON. | Pošlite platný JSON s hlavičkou Content-Type: application/json. |
| invalid_multipart | 400 | Multipart telo požiadavky je neplatné. | Skontrolujte časti multipart požiadavky a hranicu (boundary). |
| invalid_query | 400 | Query parametre požiadavky sú neplatné. | Opravte query parametre podľa dokumentácie endpointu. |
| invalid_request | 400 / 413 | Požiadavka na token nemá povinné parametre alebo má nesprávny formát. | Skontrolujte povinné parametre a formát tela podľa dokumentácie daného endpointu. |
| invalid_value | 422 / 400 | Hodnota poľa je neplatná; detail je v zozname errors. | Opravte polia uvedené v errors[].path a zopakujte požiadavku. |
| invalid_webhook | 400 / 422 | Konfigurácia webhooku je neplatná. | Opravte url a eventTypes webhooku (platná verejná HTTPS adresa). |
| ocr_processing | 409 | Dokument sa ešte spracúva rozpoznávaním textu (OCR). | Počkajte na dokončenie spracovania a zopakujte požiadavku. |
| payload_too_large | 413 | Telo požiadavky je väčšie než povolený limit. | Zmenšite telo požiadavky alebo prílohy. |
| processed_reference_conflict | 409 | Referencia spracovania dokumentu je v konflikte s už uloženou hodnotou. | Znova načítajte dokument a použite jeho aktuálnu referenciu. |
| recipient_ambiguous | 409 | Príjemcu sa nepodarilo určiť jednoznačne, zodpovedá viacero záznamov. | Upresnite príjemcu (napr. Peppol ID) a zopakujte požiadavku. |
| recipient_lookup_unavailable | 503 / 409 | Vyhľadanie príjemcu je dočasne nedostupné. | Zopakujte požiadavku neskôr. |
| recipient_not_found | 422 / 409 | Príjemca sa nenašiel. | Skontrolujte údaje príjemcu (IČO, DIČ, Peppol ID). |
| recipient_not_reachable | 422 / 409 | Príjemca nie je dosiahnuteľný cez Peppol. | Overte, či je príjemca registrovaný v Peppole, alebo doručte iným spôsobom. |
| registry_unavailable | 503 | Register zákazníkov je dočasne nedostupný. | Zopakujte požiadavku neskôr. |
| response_transition_invalid | 409 / 400 | Biznisovú odpoveď nie je možné zmeniť na požadovaný stav. | Skontrolujte aktuálny stav dokumentu a pošlite povolený prechod. |
| response_unavailable | 503 / 400 | Odoslanie biznisovej odpovede je dočasne nedostupné. | Zopakujte požiadavku neskôr. |
| source_ip_forbidden | 403 | Zdrojová IP adresa nie je pre tento API kľúč povolená. | Volajte API z povolenej IP adresy alebo ju pridajte v portáli. |
| source_scan_incomplete | 409 | Kontrola zdrojového súboru ešte nie je dokončená. | Počkajte na dokončenie kontroly a zopakujte požiadavku. |
| state_conflict | 409 | Operácia nie je v aktuálnom stave záznamu povolená. | Znova načítajte záznam a skontrolujte jeho stav. |
| test_event_unavailable | 409 | Testovaciu udalosť webhooku nie je možné odoslať. | Skontrolujte, či je webhook povolený, a zopakujte test. |
| unsafe_source_file | 409 | Zdrojový súbor bol vyhodnotený ako nebezpečný. | Nahrajte iný, bezpečný súbor. |
| unsupported_media_type | 415 | Typ obsahu požiadavky nie je podporovaný. | Použite podporovaný Content-Type (napr. application/json). |
| validation_unavailable | 503 | Validácia dokumentu je dočasne nedostupná. | Zopakujte požiadavku neskôr. |
| version_conflict | 412 | Verzia záznamu nezodpovedá hlavičke If-Match. | Znova načítajte záznam, použite jeho aktuálny ETag a zopakujte zmenu. |
| webhook_not_found | 404 | Webhook neexistuje. | Skontrolujte identifikátor webhooku. |
Katalóg kódov: OAuth 2.0 (/api/oauth)
| Kód | HTTP | Význam | Odporúčaný krok |
|---|---|---|---|
| access_denied | 403 | Firma alebo jej vlastník prístup aplikácii nepovolil, alebo je firma spravovaná centrálnymi integrátorskými prihlasovacími údajmi. | Zopakujte autorizáciu s vlastníkom firmy; pri centrálne spravovanej firme použite integrátorský API kľúč. |
| invalid_client | 401 | Neplatné prihlasovacie údaje OAuth klienta (client_id alebo client_secret). | Skontrolujte client_id a client_secret z integrátorského portálu. |
| invalid_grant | 400 / 500 | Autorizačný kód je neplatný, použitý, expirovaný alebo ho nebolo možné overiť. | Spustite autorizačný tok znova a kód vymeňte do niekoľkých minút, iba raz. |
| invalid_request | 400 / 413 | Požiadavka na token nemá povinné parametre alebo má nesprávny formát. | Skontrolujte povinné parametre a formát tela podľa dokumentácie daného endpointu. |
| invalid_scope | 400 | Požadované rozsahy (scopes) už nie sú pre klienta povolené. | Požiadajte iba o rozsahy povolené v integrátorskom portáli a zopakujte autorizáciu. |
| server_error | 500 | Vydanie integrátorských prihlasovacích údajov zlyhalo na strane servera. | Zopakujte výmenu kódu; ak chyba pretrváva, napíšte na podporu s request_id. |
| temporarily_unavailable | 503 | Politika prístupu firmy je dočasne nedostupná. | Zopakujte požiadavku o chvíľu (rešpektujte Retry-After). |
| unsupported_grant_type | 400 | Podporovaný je iba grant_type=authorization_code. | Použite grant_type=authorization_code. |
Otázky pred kontaktovaním podpory
- Ktoré rozhranie a ktorú operáciu volám a v akom prostredí?
- Ktorá firma je cieľom a akým právom k nej pristupujem?
- Ide o nové volanie alebo o opakovanie po timeoute?
Očakávaný výsledok
Pri každej chybe viete pomenovať rozhranie, právo, firmu a prostredie skôr, než napíšete podpore.
Keď to nefunguje
- Rovnaká chyba po oprave: overte, že volanie používa nové hodnoty a nie cache.
- Chyba iba v produkcii: porovnajte kľúče, identity a callbacky medzi prostrediami.