Chybové kódy

Integrujem cez

Chybová odpoveď HTTP API obsahuje okrem stavového kódu HTTP (status) aj kód chyby eKasy (code, vždy záporné číslo). Podľa neho chybu spracujte vo vašom softvéri. Formát odpovede popisuje HTTP API.

Príklad chybovej odpovede

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-104-receiptnotfound",
  "title": "Doklad sa nenašiel",
  "status": 403,
  "detail": "Dopytu nevyhovuje žiaden záznam.",
  "code": -104,
  "traceId": "0HNQ3QM5ML2BK:00000001",
  "instance": "/api/v1/requests/receipts/print_copy"
}

V závislosti od chybového kódu (vlastnosť code) sa v chybovej odpovedi môžu nachádzať ďalšie parametre, bližšie popisujúce chybový stav.

Napríklad pole key v prípade -403: StorageDuplicateKey

Kategórie chybových kódov

−1XXVšeobecné

Čas, číslo dokladu, prostredie a dostupnosť služby.

−2XXIdentifikačné údaje

Chýbajúce alebo chybné údaje podnikateľa a pokladnice.

−3XXAutentifikačné údaje

Certifikát chýba, je neplatný alebo exspiroval.

−4XXÚložisko

Pripojenie úložiska CHDÚ, kapacita a duplicitné záznamy.

−5XXTlač

Tlačiareň chýba, nie je pripravená alebo tlač zlyhala.

−6XXLicencia

Licencia eKasy je neplatná alebo neaktivovaná.

−7XXQR platby

Vytvorenie a vyhľadanie QR platby.

−900Validácia

Neplatné údaje v požiadavke.

−1000Prihlásenie

Neplatné prihlasovacie údaje alebo bezpečnostný kód Expose.

Popis chybových kódov

−1XXVšeobecné

-100: GeneralError

Všeobecná chyba

Bližšie nešpecifikovaná chyba. Konkrétnu príčinu chyby popisujú vlastnosti chybovej odpovede title a detail.

-101: ClientLocked

Klient je uzamknutý

Počas registrácie dátovej správy, došlo k chybe, ktorá zabraňuje spracovaniu takejto požiadavky v systéme finančnej správy eKasa. EKasa klient nemôže pokračovať v registrácii ďalších dátových správ.

Riešením je odstránenie príčiny, ktorá zabraňuje úspešnému odoslaniu dátovej správy a následné reštartovanie aplikácie. Takéto správanie eKasa klienta je vyžadované finančnou správou.

Príčina, pre ktorú eKasa server odmietol spracovať požiadavku, je spolu s identifikátorom požiadavky uvedená v odpovedi v poli registration.error.

Vzor poľa registration:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-101-clientlocked",
  "title": "Klient je uzamknutý",
  "status": 403,
  "detail": "EKasa klient je pozastavený, pretože počas registrácie dátovej správy s identifikátorom '0826db63-a26a-450f-8502-68543b4378be' došlo k chybe -2: Zlé vstupné hodnoty. Pre registráciu ďaľších dátových správ odstráňte príčinu chyby a odošlite neodoslané dátové správy.",
  "code": -101,
  "traceId": "0HLMCMV49LEUT:00000001",
  "registration": {
    "request": {
      "id": "0826db63-a26a-450f-8502-68543b4378be",
      "externalId": "objednavka-2026-000123",
      "originUUID": "f7f5e7c8-2598-4dfb-a0f1-d07e6207e53e"
    },
    "error": {
      "message": "Zlé vstupné hodnoty.",
      "code": -2
    }
  },
  "instance": "/api/v1/requests/receipts/cash_register"
}

Napríklad, pre chybu s kódom -10, “Chyba v podpise dátovej správy.”, je potrebné nastaviť správne prostredie eKasa klienta (integračné vs. produkčné).

-102: InvalidTime

Neplatný čas

Čas počítača je neplatný. Táto chyba nastane, ak rozdiel medzi lokálnym časom počítača a eKasa serverom prekročí stanovenú hodnotu serverTimeThresholdSeconds, nastavenú v konfigurácií klienta.

Chybu možno odstrániť úpravou lokálneho času na počítači: odporúča sa synchronizácia s internetovým časom. Kým čas nebude opravený, skončí touto chybou každá požiadavka vyžadujúca aktuálny čas, vrátane registrácie dokladu. Lokálny čas je overený so serverom vždy, keď dôjde k posunu systémových hodín väčšiemu, ako timeShiftThresholdMilliseconds, a priebežne aj bez zaznamenaného posunu.

Úprava parametra serverTimeThresholdSeconds nie je odporúčaná.

-103: InvalidReceiptNumber

Neplatné číslo dokladu

Číslo dokladu nie je platné. Chyba nastane v prípade, že systémový číselník dokladu nie je synchronizovaný s úložiskom a dokladu bolo systémom priradené číslo, ktoré sa už na úložisku nachádza. Dôvodom môže byť napr. zmazanie systémového súboru (ten je určený v konfiguračnom poli dataFilePath).

-104: ReceiptNotFound

Doklad sa nenašiel

Doklad nebol nájdený. Upravte potrebné parametre v predmetnom dopyte volania a akciu zopakujte.

-105: InvalidEKasaEnvironment

Nesprávne prostredie eKasa

Vykonanie požiadavky vyžaduje e-Kasa prostredie, ktoré je iné, ako aktuálne prednastavené. Táto chyba môže nastať, ak napr. požiadavka na registráciu dokladu alebo polohy používa ORP kód viazaný na prostredie iné, ako prednastavené alebo ak sa nahrávané identifikačné údaje viažu na rozdielne e-Kasa prostredie.

-106: ServiceUnavailable

Služba je dočasne nedostupná

Služba sa reštartuje alebo zastavuje a požiadavku nedokončila. Nastane napríklad vtedy, keď sa po zmene nastavení klient eKasa vytvára znova alebo sa API zastavuje, a požiadavka na registráciu dokladu práve čakala na vybavenie predchádzajúceho dokladu alebo na dokončenie registrácie s rovnakým externalId.

Požiadavka, ktorá čakala na vybavenie predchádzajúceho dokladu, sa do úložiska nezapísala. Ak likvidácia ukončila registráciu až po zápise do úložiska (napr. počas odosielania na server finančnej správy), požiadavka v úložisku je. Volajúci ju preto má po chvíli zopakovať s rovnakým externalId: ak sa požiadavka do úložiska zapísala alebo sa doklad medzitým zaevidoval, API vráti výsledok pôvodnej registrácie a nový doklad nevytvorí. Doklad, ktorého registráciu likvidácia ukončila až po zápise do úložiska, sa však nevytlačil a opakovaná požiadavka ho nevytlačí. Ak likvidácia preruší až tlač dokladu, API vráti chybu tlače, nie tento kód.

Kód vráti aj zoznam neodoslaných požiadaviek a zistenie nasledujúceho čísla dokladu. Iné požiadavky môžu pri likvidácii klienta skončiť aj chybou -100: GeneralError.

Chybový kód je podporovaný od verzie 9.1.0. Staršie verzie v takom prípade vrátili chybu -100: GeneralError.

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-106-serviceunavailable",
  "title": "Služba je dočasne nedostupná",
  "status": 503,
  "detail": "Služba sa reštartuje alebo zastavuje. Požiadavku zopakujte neskôr.",
  "code": -106,
  "traceId": "0HLMCMV49LEUT:00000001"
}

−2XXIdentifikačné údaje

-200: IdentityError

Chyba identifikačných údajov

Rezervované pre budúce použitie.

-201: IdentityNotFound

Identita sa nenašla

Identita s kódom on-line registračnej pokladne, uvedenom v poli cashRegisterCode, nebola nájdená. Táto chyba nastane, ak sa v úložisku nenachádza žiaden záznam identity (identifikačný údaj) s daným kódom on-line registračnej pokladne - cashRegisterCode. Nahratie požadovaných identifikačných údajov do úložiska odstráni vzniknutý problém.

−3XXAutentifikačné údaje

-300: CertificateError

Chyba certifikátu

Chyba certifikátu indikuje problém týkajúci sa certifikátu, ktorého presná príčina je uvedená v poli detail.

Príčiny:

  • nesprávne heslo uvedené v procese nahrávania nového certifikátu do úložiska
  • nesprávne alebo poškodené údaje certifikátu

Riešením je opakované nahratie certifikátu so správnym heslom, resp. so správnymi údajmi o certifikáte (pole data).

-301: CertificateNotFound

Certifikát sa nenašiel

Nebol nájdený žiaden (platný) certifikát pre identitu, uvedenú v poli cashRegisterCode. Táto chyba nastane v prípade, že do úložiska nebol doposiaľ nahratý žiaden certifikát (autentifikačný údaj) alebo existujúci certifikát už vypršal.

V oboch prípadoch sa vyžaduje nahratie nového certifikátu.

-302: CertificateExpired

Certifikát exspiroval

Certifikát, pre kód on-line registračnej pokladne s číslom uvedeným v cashRegisterCode chybovej odpovedi, exspiroval. Pred registráciou ďalšieho dokladu alebo polohy je nutné nahrať nový platný certifikát.

−4XXÚložisko

-400: StorageError

Chyba pri práci s úložiskom

Bližšie nešpecifikovaná chyba, ktorá nastala v súvislosti s prácou s chráneným dátovým úložiskom (čítanie resp. zápis na dátové úložisko alebo čítanie resp. zápis do pomocnej tabuľky indexov dátového úložiska).

Najbežnejšie príčiny sú, že dátové úložisko nie je pripojené k systému, alebo je v konfigurácii uvedený nesprávny názov sériového portu.

-401: StorageInsufficientSpace

Úložisko je plné

Zázam sa nepodarilo uložiť s dôvodu nedostatočnej voľnej kapacity dátového média chráneného dátového úložiska.

-402: StorageDICMismatch

Nezhoda DIČ

Do úložiska bol vykonaný pokus o zápis záznamu s DIČ hodnotou inou, ako je DIČ hodnota úložiska.

Úložisko je viazané na jeden podnikateľský subjekt, identifikovaný pomocou DIČ.

Pokus o vloženie identifikačných alebo autentifikačných údajov, prípadne dátovej správy (dokladu alebo polohy), ktorá neprislúcha tomuto podnikateľskému subjektu bude zamietnutý touto chybou.

-403: StorageDuplicateKey

Duplicitný identifikátor

Zápis do úložiska zlyhal, nakoľko pre daný kód on-line registračnej pokladne už v úložisku existuje záznam s rovnakým identifikátorom a tieto záznamy sú po svojej obsahovej stránke rôzne.

Vzor odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-403-storageduplicatekey",
  "title": "Duplicitný identifikátor",
  "status": 500,
  "detail": "Záznam s externým identifikátorom 'objednavka-2026-000123' už existuje.",
  "code": -403,
  "traceId": "0HLMDGC781MUH:00000002",
  "cashRegisterCode": "88812345678900001",
  "key": {
    "name": "RegistrationRequestExternalId",
    "value": "objednavka-2026-000123"
  },
  "instance": "/api/v1/requests/receipts/cash_register"
}

Úložisko si pred zápisom požiadavky overí unikátnosť:

  • identifikátora požiadavky (id)
  • externého identifikátora požiadavky: (externalId)
  • v prípade registrácie dokladu aj unikátnosť čísla dokladu (receiptNumber)

Za účelom bližšej identifikácie indexu, ktorého unikátnosť je porušená, sa v tele odpovede nachádza pole key.

Pole key obsahuje názov indexu porušujúceho unikátnosť (name) a jeho hodnotu (value).

Pole name nadobúda v závislosti od typu indexu tieto hodnoty:

Index Hodnota key.name Riešenie
Interné id RegistrationRequestId Pravdepodobnosť duplicitnej hodnoty pre interný identifikátor (Id) je extrémne nízka. V prípade výskytu je riešením opakovanie požiadavky.
Externé id RegistrationRequestExternalId V prípade duplicitnej hodnoty pre externý identifikátor (ExternalId) je potrebné hľadať príčinu v nadradenej aplikácií. Riešením je zopakovať požiadavku s novou hodnotou externého identifikátora.
Číslo dokladu ReceiptRegistrationRequestReceiptId Zhoda ReceiptNumber indikuje nezosynchronizovaný číselník dokladov s úložiskom. V tomto prípade ide o zlyhanie eKasa aplikácie. Odporúča sa aktualizovať eKasa API na najnovšiu dostupnú verziu.

Konkrétnu príčinu chyby popisujú vlastnosti chybovej odpovede title a detail.

-404: StorageNotFound

Úložisko sa nenašlo

Chyba nastane, ak nastavenie úložiska nemá vyplnenú hodnotu StorageModel alebo ChduSerialPortName a zároveň nebolo k zariadeniu pripojené žiadne z kompatibilných dátových úložísk.

-405: StorageAmbiguity

Nejednoznačné úložisko

Chyba nastane, ak nastavenie úložiska nemá vyplnenú hodnotu StorageModel alebo ChduSerialPortName a zároveň bolo k zariadeniu pripojených viacero kompatibilných dátových úložísk.

-406: StorageForbiddenEKasaEnvironment

Nesprávne prostredie úložiska

Chyba nastane, ak úložisko bolo použité na nepodporované e-Kasa prostredie, napr. InMemory úložisko bolo použité na produkčné (Production) prostredie.

-407: StorageForbiddenDeviceModel

Nepodporovaný model zariadenia

Táto chyba vznikne v prípade, že úložisko je použité na nepodporovanom modeli zariadenia. Najčastejšie sa týka úložiska SwissBit, ktorého použitie je povolené výhradne na zariadeniach, ktoré absolvovali certifikačné konanie v súvislosti s aplikáciou eKasa na Finančnej správe SR.

Použitie úložiska SwissBit na inom než certifikovanom modeli zariadenia nie je povolené a vedie k vzniku tejto chyby. Výnimku tvorí režim tzv. technického dema, kedy je aplikácia viazaná výhradne na integračné prostredie systému eKasa za účelom overenia kompatibility zariadenia.

−5XXTlač

-500: PrinterError

Tlačiareň ohlásila chybu

Všeobecná chyba tlače na tlačiarni s názvom uvedeným v poli printerName. Presné príčiny zlyhania tlače sú uvedené v poli detail chybovej odpovede.

-501: PrinterNotFound

Tlačiareň sa nenašla

Tlačiareň s názvom, uvedeným v premennej printerName chybovej odpovedi, nebola nájdená a doklad nemôže byť vytlačený. Riešením je použiť, v každej ďalšiej požiadavke o zaevidovanie dokladu alebo polohy, jeden z platných názvov tlačiarní a to buď pos, pdf alebo email.

-502: PrintReceiptError

Tlač dokladu zlyhala

Tlač dokladu zlyhala. Ak chyba nastala počas požiadavky evidencie dokladu, doklad možno považovať za zaevidovaný eKasa serverom. Neposielajte ho preto na registráciu znova. Zákazníkovi môžete vytlačiť kópiu dokladu, pričom v požiadavke sa uvedie jeden z jeho identifikátorov, uvedený v chybovej odpovedi a to buď requestExternalId, ak bol uvedený, alebo receiptId. Ak zákazník trvá na origináli, pôvodný doklad stornujte a zaregistrujte nový.

Príklad chybovej odpovede zlyhanej požiadavky spracovania dokladu:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-502-printreceiptererror",
  "title": "Tlač dokladu zlyhala",
  "status": 500,
  "detail": "Tlač dokladu č. 21 z 6/2026 pokladne 88812345678900001 na tlačiarni 'pos' zlyhala.",
  "code": -502,
  "traceId": "0HLNDFM9VMUHB:00000001",
  "printerName": "pos",
  "receiptId": {
    "cashRegisterCode": "88812345678900001",
    "year": 2026,
    "month": 6,
    "receiptNumber": 21
  },
  "requestExternalId": null,
  "instance": "/api/v1/requests/receipts/cash_register"
}

Následná požiadavka o vytlačenie kópie dokladu môže vyzerať nasledovne: {server_address}/api/v1/requests/receipts/print_copy?cashRegisterCode=88812345678900001&year=2026&month=6&receiptNumber=21

-503: PrinterNotReady

Tlačiareň nie je pripravená

Tlačiareň s názvom, uvedeným v premennej printerName chybovej odpovedi, nie je pripojená a akcia súvisiaca s tlačiarňou nemôže byť dokončená. Riešením je overiť, či je tlačiareň fyzicky pripojená k úložisku a zapnutá.

Niektoré modely chráneného dátového úložiska (napríklad CHDU-SK) však umožňujú vykonanie akcie súvisiacej s tlačou aj napriek nepripravenej tlačiarni. Z tohto dôvodu majú niektoré akcie (tlač nefiskálneho dokladu, tlač kópie dokladu, tlač neodoslaných dátových správ, otvorenie peňažnej zásuvky, …) vo svojich návratových modeloch vlastnosť printed.

−6XXLicencia

-600: LicenseError

Chyba licencie

Pridané od verzie eKasa API 7.0.0.

Chyba licencie indikuje problém týkajúci sa licencie, ktorého presná príčina je uvedená v poli detail.

-601: LicenseInvalidError

Licencia je neplatná

Licencia je neplatná. Táto chyba nastane, ak licencia pre úložisko nie je platná alebo ak niektoré z používaných rozšírení nie sú platné.

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-601-licenseinvaliderror",
  "title": "Licencia je neplatná",
  "status": 500,
  "detail": "Licencia pre balík 'ekasa' vo verzii '9.0.7' nie je pre toto úložisko platná.",
  "code": -601,
  "traceId": "0HLNDIHB0GA61:00000001",
  "storage": {
    "isValid": true,
    "customerWarranty": {
      "start": "2025-10-01T00:00:00",
      "end": "2026-10-31T23:59:59"
    },
    "error": {
      "message": "Úložisko nie je v záruke",
      "code": -104
    }
  },
  "features": [
    {
      "sku": "ekasa",
      "isValid": false,
      "version": "9.0.7",
      "validity": {
        "start": "2025-10-01T00:00:00",
        "end": "2026-10-31T23:59:59"
      },
      "error": {
        "message": "Licencia pre balík 'ekasa' vo verzii '9.0.7' nie je pre toto úložisko platná",
        "code": -203
      }
    }
  ]
}

-602: LicenseNotActivated

Licencia nie je aktivovaná

API odmietlo obslúžiť požiadavku, pretože zariadenie nemá aktivovanú licenciu. Aktivácia licencie nastáva pri prvom spustení aplikácie a jej priebeh či inštrukcie možno sledovať na obrazovke zariadenia.

Volajúci by mal používateľa nasmerovať na dokončenie aktivačného procesu v samotnej aplikácii (QR kód alebo ručné zadanie kódu od technika).

Chybový kód je podporovaný od verzie 8.0.3 na platforme Android.

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-602-licensenotactivated",
  "title": "Licencia nie je aktivovaná",
  "status": 503,
  "detail": "Licencia nie je aktivovaná.",
  "code": -602,
  "traceId": null
}

-603: LicenseVerificationInProgress

Prebieha overovanie licencie

Lokálne API je dočasne nedostupné, pretože práve prebieha štartovacie overovanie stavu zariadenia voči onboarding backendu. Ide o prechodný stav, ktorý typicky trvá iba prvé sekundy po spustení aplikácie — kým sa dokončí kontrola licencie.

Volajúci by mal požiadavku po krátkej pauze zopakovať (napr. 3–5 sekúnd).

Po úspešnom overení API automaticky prejde do režimu obsluhy požiadaviek; pri neúspechu sa stav zmení na -602 LicenseNotActivated.

Chybový kód je podporovaný od verzie 8.0.3 na platforme Android.

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-603-licenseverificationinprogress",
  "title": "Prebieha overovanie licencie",
  "status": 503,
  "detail": "Prebieha overovanie licencie.",
  "code": -603,
  "traceId": null
}

−7XXQR platby

-700: QrPaymentError

Chyba QR platby

Nastala chyba súvisiaca so spracovaním QR platby.

Bližšiu príčinu určuje správa v tele odpovede.

-701: QrPaymentInitializationError

Chyba vytvorenia QR platby

Nastala chyba pri vytváraní QR platby.

Medzi možné príčiny patrí:

  • Nepodarilo sa nadviazať sieťové spojenie so službou okamžitých platieb
    • z dôvodu výpadku sieťového pripojenia na eKasa zariadení
    • z dôvodu výpadku služby finančnej správy
  • Nadviazanie zabezpečeného sietoťového spojenia bolo zamietnuté službou okamžitých platieb

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-701-qrpaymentinitializationerror",
  "title": "Chyba vytvorenia QR platby",
  "status": 500,
  "detail": "Nepodarilo sa nadviazať sieťové spojenie so službou okamžitých platieb.",
  "code": -701,
  "traceId": "0HNGIPOQC63UF:00000002",
  "instance": "/api/v1/payments/qr"
}

-702: QrPaymentNotFoundError

QR platba sa nenašla

QR platba s daným identifikátorom nebola nájdená.

Medzi možné príčiny patrí:

  • eKasa aplikácia bola od momentu vytvorenia QR platby reštartovaná
  • QR platba exspirovala a po uplynutí časového limitu bola vyradená z evidencie.

HTTP kód odpovede je 404.

Príklad chybovej odpovede:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-702-qrpaymentnotfoundnerror",
  "title": "QR platba nebola nájdená",
  "status": 404,
  "detail": "QR platba s identifikátorom '00000000-0000-0000-0000-000000000000' nebola nájdená.",
  "code": -702,
  "traceId": null
}

−900Validácia

-900: ValidationError

Validácia zlyhala

Validácia zlyhala. Server nemôže spracovať požiadavku, nakoľko obsahuje neplatné dáta. Chybné polia a ich príčiny sú uvedené v poli errors.

Príklad chybovej odpovede požiadavky s neplatnými údajmi:

{
  "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#900-validationerror",
  "title": "Validácia zlyhala",
  "status": 400,
  "traceId": "0HNQ3QM5ML2AH:00000001",
  "code": -900,
  "errors": {
    "Request.Data.CashRegisterCode": [
      "Pole 'Cash Register Code' nemá správny formát."
    ]
  },
  "instance": "/api/v1/requests/receipts/cash_register"
}

−1000Prihlásenie

-1000: Unauthenticated

Nie ste prihlásený

Pridané od verzie eKasa API 6.7.1.

Požiadavka nebola autentifikovaná. Táto chyba nastane, ak

  • je zapnuté zabezpečenie a požiadavka obsahuje neplatné prihlasovacie údaje (hodnota authScheme v odpovedi má hodnotu Basic)
  • ak bola vykonaná požiadavka na eKasa API cez službu Expose s neplatným bezpečnostným kódom (hodnota authScheme v odpovedi má hodnotu AccessToken)
{
    "authScheme": "AccessToken",
    "traceId": "0HMVHH6PS1J6J:00000002",
    "code": -1000,
    "type": "https://ekasa.ninedigit.sk/docs/rest-api/error-codes#-1000-unauthenticated",
    "title": "Nie ste prihlásený",
    "status": 401,
    "detail": null,
    "instance": "/api/v1/product/info",
    "extensions": {}
}
Esc

↑↓ výberEnter otvoriťEsc zavrieť

Chýba vám niečo v dokumentácii?

Napíšte nám, s čím potrebujete pomôcť. Ozveme sa do pár hodín.

Údaje použijeme len na odpoveď. Viac v ochrane osobných údajov.