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
Čas, číslo dokladu, prostredie a dostupnosť služby.
Chýbajúce alebo chybné údaje podnikateľa a pokladnice.
Certifikát chýba, je neplatný alebo exspiroval.
Pripojenie úložiska CHDÚ, kapacita a duplicitné záznamy.
-400Chyba pri práci s úložiskomStorageError-401Úložisko je plnéStorageInsufficientSpace-402Nezhoda DIČStorageDICMismatch-403Duplicitný identifikátorStorageDuplicateKey-404Úložisko sa nenašloStorageNotFound-405Nejednoznačné úložiskoStorageAmbiguity-406Nesprávne prostredie úložiskaStorageForbiddenEKasaEnvironment-407Nepodporovaný model zariadeniaStorageForbiddenDeviceModel
Tlačiareň chýba, nie je pripravená alebo tlač zlyhala.
Licencia eKasy je neplatná alebo neaktivovaná.
Vytvorenie a vyhľadanie QR platby.
Neplatné údaje v požiadavke.
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
authSchemev odpovedi má hodnotuBasic) - ak bola vykonaná požiadavka na eKasa API cez službu Expose s neplatným bezpečnostným kódom (hodnota
authSchemev odpovedi má hodnotuAccessToken)
{
"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": {}
}