Besides the HTTP status code (status), an HTTP API error response contains an eKasa error code (code, always a
negative number). Handle the error in your software based on this code. The response format is described in
HTTP API.
Error response example
{
"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"
}
Depending on the error code (the code property), the error response may contain further parameters that describe
the error in more detail.
For example, the key field in the case of -403: StorageDuplicateKey.
Error code categories
Time, receipt number, environment and service availability.
Missing or invalid business and cash register data.
The certificate is missing, invalid or expired.
CHDÚ storage connection, capacity and duplicate records.
-400Storage errorStorageError-401Storage is fullStorageInsufficientSpace-402Tax ID mismatchStorageDICMismatch-403Duplicate identifierStorageDuplicateKey-404Storage not foundStorageNotFound-405Ambiguous storageStorageAmbiguity-406Wrong storage environmentStorageForbiddenEKasaEnvironment-407Unsupported device modelStorageForbiddenDeviceModel
The printer is missing, not ready or printing failed.
The eKasa licence is invalid or not activated.
Creating and finding a QR payment.
Invalid data in the request.
Invalid credentials or Expose security code.
Error code descriptions
−1XXGeneral
-100: GeneralError
General error
An unspecified error. The exact cause is described by the title and detail properties of the error response.
-101: ClientLocked
Client is locked
While a data message was being registered, an error occurred that prevents the request from being processed in the Financial Administration’s eKasa system. The eKasa client cannot continue registering further data messages.
The solution is to remove the cause that prevents the data message from being sent successfully and then restart the application. The Financial Administration requires the eKasa client to behave this way.
The reason why the eKasa server refused to process the request is given, together with the request identifier, in the
registration.error field of the response.
Sample registration field:
{
"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"
}
For example, error code -10, “Chyba v podpise dátovej správy.” (error in the data message signature), means that
the receipt reached a different environment than the one the initialization package is for. Set the environment to
automatic (see the FAQ).
-102: InvalidTime
Invalid time
The computer’s time is invalid. This error occurs when the difference between the computer’s local time and the eKasa
server exceeds the serverTimeThresholdSeconds value set in the client configuration.
You can fix the error by correcting the computer’s local time; synchronising with internet time is recommended.
Until the time is corrected, every request that needs the current time fails with this error, including receipt
registration. The local time is checked against the server whenever the system clock shifts by more than
timeShiftThresholdMilliseconds, and also periodically when no shift is detected.
Changing the serverTimeThresholdSeconds parameter is not recommended.
-103: InvalidReceiptNumber
Invalid receipt number
The receipt number is not valid. The error occurs when the system receipt counter is not synchronised with the
storage and the system assigned the receipt a number that already exists in the storage. The cause can be, for
example, deleting the system file (set in the dataFilePath configuration field).
-104: ReceiptNotFound
Receipt not found
The receipt was not found. Adjust the parameters of the request and try again.
-105: InvalidEKasaEnvironment
Wrong eKasa environment
The request requires an eKasa environment other than the one currently set. This error can occur, for example, when a receipt or location registration request uses a cash register code (ORP) bound to an environment other than the one set, or when the identification data being uploaded are bound to a different eKasa environment.
-106: ServiceUnavailable
Service temporarily unavailable
The service is restarting or stopping and did not complete the request. This happens, for example, when the eKasa
client is being recreated after a settings change or the API is stopping, and a receipt registration request was
waiting for the previous receipt to finish or for a registration with the same externalId to complete.
A request that was waiting for the previous receipt was not written to the storage. If the shutdown ended the
registration only after it was written to the storage (for example while it was being sent to the Financial
Administration server), the request is in the storage. The caller should therefore repeat it after a while with the
same externalId: if the request was written to the storage or the receipt was recorded in the meantime, the API
returns the result of the original registration and does not create a new receipt. However, a receipt whose
registration the shutdown ended only after it was written to the storage was not printed, and the repeated request
does not print it. If the shutdown interrupts only the printing of the receipt, the API returns a printing error, not
this code.
The code is also returned by the list of unsent requests and by the lookup of the next receipt number. Other requests may also fail with -100: GeneralError while the client is shutting down.
This error code is supported from version 9.1.0. Older versions returned -100: GeneralError in this case.
Error response example:
{
"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"
}
−2XXIdentification data
-200: IdentityError
Identification data error
Reserved for future use.
-201: IdentityNotFound
Identity not found
The identity with the online cash register code given in the cashRegisterCode field was not found. This error
occurs when the storage contains no identity record (identification data) with that online cash register code
(cashRegisterCode). Uploading the required identification data to the storage resolves the problem.
−3XXAuthentication data
-300: CertificateError
Certificate error
A certificate error indicates a problem with a certificate; the exact cause is given in the detail field.
Causes:
- an incorrect password entered while uploading a new certificate to the storage
- incorrect or corrupted certificate data
The solution is to upload the certificate again with the correct password or with the correct certificate data (the
data field).
-301: CertificateNotFound
Certificate not found
No (valid) certificate was found for the identity given in the cashRegisterCode field. This error occurs when no
certificate (authentication data) has been uploaded to the storage yet, or the existing certificate has already
expired.
In both cases, you need to upload a new certificate.
-302: CertificateExpired
Certificate expired
The certificate for the online cash register code given in cashRegisterCode of the error response has expired.
Before registering another receipt or location, you must upload a new valid certificate.
−4XXStorage
-400: StorageError
Storage error
An unspecified error related to working with the protected data storage (reading from or writing to the data storage, or reading from or writing to the storage’s auxiliary index table).
The most common causes are that the data storage is not connected to the system, or that the configuration contains an incorrect serial port name.
-401: StorageInsufficientSpace
Storage is full
The record could not be saved because there is not enough free capacity on the protected data storage medium.
-402: StorageDICMismatch
Tax ID mismatch
There was an attempt to write a record with a tax ID (DIČ) different from the storage’s DIČ.
The storage is bound to one business, identified by its DIČ.
An attempt to insert identification or authentication data, or a data message (receipt or location), that does not belong to this business is rejected with this error.
-403: StorageDuplicateKey
Duplicate identifier
Writing to the storage failed because, for the given online cash register code, the storage already contains a record with the same identifier and the two records differ in content.
Sample response:
{
"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"
}
Before writing a request, the storage checks the uniqueness of:
- the request identifier (
id) - the external request identifier (
externalId) - for receipt registration, also the receipt number (
receiptNumber)
To identify the index whose uniqueness is violated, the response body contains the key field.
The key field contains the name of the index violating uniqueness (name) and its value (value).
Depending on the index type, the name field takes these values:
| Index | key.name value |
Solution |
|---|---|---|
| Internal id | RegistrationRequestId |
The probability of a duplicate internal identifier (Id) is extremely low. If it happens, repeat the request. |
| External id | RegistrationRequestExternalId |
A duplicate external identifier (ExternalId) points to a cause in the calling application. Repeat the request with a new external identifier. |
| Receipt number | ReceiptRegistrationRequestReceiptId |
A matching ReceiptNumber indicates that the receipt counter is not synchronised with the storage. This is a failure of the eKasa application. We recommend updating the eKasa API to the latest available version. |
The exact cause of the error is described by the title and detail properties of the error response.
-404: StorageNotFound
Storage not found
The error occurs when the storage settings have no StorageModel or ChduSerialPortName value and, at the same
time, no compatible data storage is connected to the device.
-405: StorageAmbiguity
Ambiguous storage
The error occurs when the storage settings have no StorageModel or ChduSerialPortName value and, at the same
time, several compatible data storages are connected to the device.
-406: StorageForbiddenEKasaEnvironment
Wrong storage environment
The error occurs when the storage is used with an unsupported eKasa environment, for example an InMemory storage
used with the production (Production) environment.
-407: StorageForbiddenDeviceModel
Unsupported device model
This error occurs when the storage is used on an unsupported device model.
It most often concerns the SwissBit storage, which may be used only on devices that have passed certification of
the eKasa application by the Financial Administration of the Slovak Republic.
Using the SwissBit storage on a device model other than a certified one is not allowed and results in this error. The exception is the so-called technical demo mode, in which the application is bound exclusively to the integration environment of the eKasa system in order to verify device compatibility.
−5XXPrinting
-500: PrinterError
Printer reported an error
A general printing error on the printer named in the printerName field. The exact causes of the printing failure
are given in the detail field of the error response.
-501: PrinterNotFound
Printer not found
The printer named in the printerName variable of the error response was not found and the receipt cannot be
printed. The solution is to use one of the valid printer names, pos, pdf or email, in every further receipt or
location registration request.
-502: PrintReceiptError
Receipt printing failed
Printing the receipt failed. If the error occurred during a receipt registration request, the receipt can be
considered registered by the eKasa server, so do not send it for registration again. You can print a copy of the
receipt for the customer; the request for the copy uses one of the receipt identifiers given in the error response,
either requestExternalId if it was provided, or receiptId. If the customer insists on the original,
cancel the original receipt and register a new one.
Example error response of a failed receipt processing request:
{
"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"
}
The follow-up request to print a copy of the receipt can look like this:
{server_address}/api/v1/requests/receipts/print_copy?cashRegisterCode=88812345678900001&year=2026&month=6&receiptNumber=21
-503: PrinterNotReady
Printer not ready
The printer named in the printerName variable of the error response is not connected and the printer-related action
cannot be completed. The solution is to check that the printer is physically connected to the storage and switched on.
Some protected data storage models (for example CHDU-SK), however, allow a printing-related action to be performed
even though the printer is not ready. For this reason, some actions (printing a non-fiscal receipt, printing a copy of
a receipt, printing unsent data messages, opening the cash drawer, …) have a printed property in their return
models.
−6XXLicence
-600: LicenseError
Licence error
Added in eKasa API version 7.0.0.
A licence error indicates a problem with the licence; the exact cause is given in the detail field.
-601: LicenseInvalidError
Licence is invalid
The licence is invalid. This error occurs when the licence for the storage is not valid or when some of the extensions in use are not valid.
Error response example:
{
"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
Licence not activated
The API refused to handle the request because the device does not have an activated licence. The licence is activated when the application is first started; you can follow its progress and instructions on the device screen.
The caller should direct the user to complete the activation process in the application itself (a QR code or manual entry of a code from a technician).
This error code is supported from version 8.0.3 on Android.
Error response example:
{
"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
Licence verification in progress
The local API is temporarily unavailable because the start-up check of the device state against the onboarding backend is in progress. This is a transient state that typically lasts only the first few seconds after the application starts, until the licence check completes.
The caller should repeat the request after a short pause (for example 3–5 seconds).
After successful verification, the API automatically starts handling requests; if verification fails, the state
changes to -602 LicenseNotActivated.
This error code is supported from version 8.0.3 on Android.
Error response example:
{
"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 payments
-700: QrPaymentError
QR payment error
An error occurred while processing a QR payment.
The exact cause is given by the message in the response body.
-701: QrPaymentInitializationError
QR payment could not be created
An error occurred while creating a QR payment.
Possible causes include:
- The network connection to the instant payment service could not be established
- because of a network outage on the eKasa device
- because of an outage of the Financial Administration service
- The instant payment service refused to establish a secure network connection
Error response example:
{
"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 payment not found
The QR payment with the given identifier was not found.
Possible causes include:
- the eKasa application was restarted after the QR payment was created
- the QR payment expired and was removed from the records after the time limit.
The HTTP response code is 404.
Error response example:
{
"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
}
−900Validation
-900: ValidationError
Validation failed
Validation failed. The server cannot process the request because it contains invalid data. The invalid fields and
their causes are listed in the errors field.
Example error response of a request with invalid data:
{
"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"
}
−1000Sign-in
-1000: Unauthenticated
Not signed in
Added in eKasa API version 6.7.1.
The request was not authenticated. This error occurs when
- security is enabled and the request contains invalid credentials (the
authSchemevalue in the response isBasic) - a request was made to the eKasa API through the Expose service with an invalid security code (the
authSchemevalue in the response isAccessToken)
{
"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": {}
}