Error codes

Integrating via

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

−1XXGeneral

Time, receipt number, environment and service availability.

−2XXIdentification data

Missing or invalid business and cash register data.

−3XXAuthentication data

The certificate is missing, invalid or expired.

−4XXStorage

CHDÚ storage connection, capacity and duplicate records.

−5XXPrinting

The printer is missing, not ready or printing failed.

−6XXLicence

The eKasa licence is invalid or not activated.

−7XXQR payments

Creating and finding a QR payment.

−900Validation

Invalid data in the request.

−1000Sign-in

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 authScheme value in the response is Basic)
  • a request was made to the eKasa API through the Expose service with an invalid security code (the authScheme value in the response is 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

↑↓ selectEnter openEsc close

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.