# Error codes

> Meaning of the error codes (the code property) in eKasa HTTP API error responses, with examples.

Source: https://ekasa.ninedigit.sk/en/docs/rest-api/error-codes

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](https://ekasa.ninedigit.sk/en/docs/rest-api#error-responses).

## Error response example

```json
{
  "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](#-403-storageduplicatekey).

## Error code categories

### General (-1XX)

Time, receipt number, environment and service availability.

- [-100 GeneralError](#-100-generalerror): General error
- [-101 ClientLocked](#-101-clientlocked): Client is locked
- [-102 InvalidTime](#-102-invalidtime): Invalid time
- [-103 InvalidReceiptNumber](#-103-invalidreceiptnumber): Invalid receipt number
- [-104 ReceiptNotFound](#-104-receiptnotfound): Receipt not found
- [-105 InvalidEKasaEnvironment](#-105-invalidekasaenvironment): Wrong eKasa environment
- [-106 ServiceUnavailable](#-106-serviceunavailable): Service temporarily unavailable

### Identification data (-2XX)

Missing or invalid business and cash register data.

- [-200 IdentityError](#-200-identityerror): Identification data error
- [-201 IdentityNotFound](#-201-identitynotfound): Identity not found

### Authentication data (-3XX)

The certificate is missing, invalid or expired.

- [-300 CertificateError](#-300-certificateerror): Certificate error
- [-301 CertificateNotFound](#-301-certificatenotfound): Certificate not found
- [-302 CertificateExpired](#-302-certificateexpired): Certificate expired

### Storage (-4XX)

CHDÚ storage connection, capacity and duplicate records.

- [-400 StorageError](#-400-storageerror): Storage error
- [-401 StorageInsufficientSpace](#-401-storageinsufficientspace): Storage is full
- [-402 StorageDICMismatch](#-402-storagedicmismatch): Tax ID mismatch
- [-403 StorageDuplicateKey](#-403-storageduplicatekey): Duplicate identifier
- [-404 StorageNotFound](#-404-storagenotfound): Storage not found
- [-405 StorageAmbiguity](#-405-storageambiguity): Ambiguous storage
- [-406 StorageForbiddenEKasaEnvironment](#-406-storageforbiddenekasaenvironment): Wrong storage environment
- [-407 StorageForbiddenDeviceModel](#-407-storageforbiddendevicemodel): Unsupported device model

### Printing (-5XX)

The printer is missing, not ready or printing failed.

- [-500 PrinterError](#-500-printererror): Printer reported an error
- [-501 PrinterNotFound](#-501-printernotfound): Printer not found
- [-502 PrintReceiptError](#-502-printreceipterror): Receipt printing failed
- [-503 PrinterNotReady](#-503-printernotready): Printer not ready

### Licence (-6XX)

The eKasa licence is invalid or not activated.

- [-600 LicenseError](#-600-licenseerror): Licence error
- [-601 LicenseInvalidError](#-601-licenseinvaliderror): Licence is invalid
- [-602 LicenseNotActivated](#-602-licensenotactivated): Licence not activated
- [-603 LicenseVerificationInProgress](#-603-licenseverificationinprogress): Licence verification in progress

### QR payments (-7XX)

Creating and finding a QR payment.

- [-700 QrPaymentError](#-700-qrpaymenterror): QR payment error
- [-701 QrPaymentInitializationError](#-701-qrpaymentinitializationerror): QR payment could not be created
- [-702 QrPaymentNotFoundError](#-702-qrpaymentnotfounderror): QR payment not found

### Validation (-900)

Invalid data in the request.

- [-900 ValidationError](#-900-validationerror): Validation failed

### Sign-in (-1000)

Invalid credentials or Expose security code.

- [-1000 Unauthenticated](#-1000-unauthenticated): Not signed in

## Error code descriptions

<p class="error-group-head"><span class="error-range">−1XX</span>General</p>

### `-100: GeneralError`

<p class="error-title">General error</p>

An unspecified error. The exact cause is described by the `title` and `detail` properties of the error response.

### `-101: ClientLocked`

<p class="error-title">Client is locked</p>

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:

```json
{
  "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](https://ekasa.ninedigit.sk/en/docs/faq#invalid-data-message-signature)).

### `-102: InvalidTime`

<p class="error-title">Invalid time</p>

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`

<p class="error-title">Invalid receipt number</p>

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`

<p class="error-title">Receipt not found</p>

The receipt was not found. Adjust the parameters of the request and try again.

### `-105: InvalidEKasaEnvironment`

<p class="error-title">Wrong eKasa environment</p>

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`

<p class="error-title">Service temporarily unavailable</p>

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](#-100-generalerror) while the client is shutting down.

This error code is supported from version 9.1.0. Older versions returned
[-100: GeneralError](#-100-generalerror) in this case.

Error response example:

```json
{
  "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"
}
```

<p class="error-group-head"><span class="error-range">−2XX</span>Identification data</p>

### `-200: IdentityError`

<p class="error-title">Identification data error</p>

*Reserved for future use.*

### `-201: IdentityNotFound`

<p class="error-title">Identity not found</p>

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.

<p class="error-group-head"><span class="error-range">−3XX</span>Authentication data</p>

### `-300: CertificateError`

<p class="error-title">Certificate error</p>

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`

<p class="error-title">Certificate not found</p>

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`

<p class="error-title">Certificate expired</p>

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.

<p class="error-group-head"><span class="error-range">−4XX</span>Storage</p>

### `-400: StorageError`

<p class="error-title">Storage error</p>

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`

<p class="error-title">Storage is full</p>

The record could not be saved because there is not enough free capacity on the protected data storage medium.

### `-402: StorageDICMismatch`

<p class="error-title">Tax ID mismatch</p>

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`

<p class="error-title">Duplicate identifier</p>

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:

```json
{
  "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`

<p class="error-title">Storage not found</p>

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`

<p class="error-title">Ambiguous storage</p>

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`

<p class="error-title">Wrong storage environment</p>

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`

<p class="error-title">Unsupported device model</p>

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.

<p class="error-group-head"><span class="error-range">−5XX</span>Printing</p>

### `-500: PrinterError`

<p class="error-title">Printer reported an error</p>

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`

<p class="error-title">Printer not found</p>

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.

### <span id="-502-printreceiptererror" class="anchor"></span>`-502: PrintReceiptError`

<p class="error-title">Receipt printing failed</p>

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](https://ekasa.ninedigit.sk/en/docs/receipt-registration/corrections#receipt-cancellation) the original receipt and register a new one.

Example error response of a failed receipt processing request:

```json
{
  "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`

<p class="error-title">Printer not ready</p>

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.

<p class="error-group-head"><span class="error-range">−6XX</span>Licence</p>

### `-600: LicenseError`

<p class="error-title">Licence error</p>

*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`

<p class="error-title">Licence is invalid</p>

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:

```json
{
  "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`

<p class="error-title">Licence not activated</p>

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:

```json
{
  "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`

<p class="error-title">Licence verification in progress</p>

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:

```json
{
  "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
}
```

<p class="error-group-head"><span class="error-range">−7XX</span>QR payments</p>

### `-700: QrPaymentError`

<p class="error-title">QR payment error</p>

An error occurred while processing a QR payment.

The exact cause is given by the message in the response body.

### `-701: QrPaymentInitializationError`

<p class="error-title">QR payment could not be created</p>

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:

```json
{
  "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"
}
```

### <span id="-702-qrpaymentnotfoundnerror" class="anchor"></span>`-702: QrPaymentNotFoundError`

<p class="error-title">QR payment not found</p>

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:

```json
{
  "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
}
```

<p class="error-group-head"><span class="error-range">−900</span>Validation</p>

### <span id="900-validationerror" class="anchor"></span>`-900: ValidationError`

<p class="error-title">Validation failed</p>

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:

```json
{
  "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"
}
```

<p class="error-group-head"><span class="error-range">−1000</span>Sign-in</p>

### `-1000: Unauthenticated`

<p class="error-title">Not signed in</p>

*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": {}
}
```
