Error and Timeout Handling

The top priority when implementing the fiskaly SIGN DE API is to keep the POS system up and running at all times.

⚠️Don't block the till

There is no obligation that the till should stop its operation or be heavily affected at any point in time. Make sure that your integration is not blocking the operators.

In the optimal case, the API is implemented in such a way that the smooth operation of the cash register can be guaranteed at all times. Here’s how to achieve this.

Set Timeouts Correctly

In the event that the TSS is unavailable or temporarily unstable, the checkout process must not be disrupted. Timeouts depend heavily on the frequency of the POS system. As a manufacturer, you should decide which timeout length you consider reasonable. No request should ever be open long enough to jeopardize smooth cash register operation.

Recommended Timeout Values

Endpoint	Recommended Timeout	Notes
Transaction endpoints	3 - 5 seconds	Most critical for checkout flow
TSS creation & personalization	30 seconds minimum	One-time setup operation
Authorization	3 - 4 seconds	Token refresh, not every request
DSFinV-K endpoints	Up to 10 minutes	Heavy processing / data exports

💡Make timeouts configurable

We recommend creating the possibility for timeouts to be set (e.g., a value between 1.5 - 3 seconds) by an administrator. This way, valuable development resources can be saved and smooth POS operation is possible.

📘Note

If there seems to be a problem, please check status.fiskaly.com as well as the support page.

Handling Errors Gracefully

When a request fails or times out, follow this approach:

1. Detect the failure

   Set appropriate timeouts per endpoint type (see table above). When a timeout or HTTP error occurs, catch it gracefully without blocking the checkout.

2. Continue the checkout

   Allow the transaction to proceed even without a TSS signature. Record the transaction locally with all available data.

3. Mark the receipt

   Add a clear note on the receipt such as “TSS not available” or “TSS signing failed” as recommended by the financial authorities.

4. Record in DSFinV-K

   Ensure the unsigned transaction appears in the DSFinV-K export using the transactions.security.error_message field instead of transactions.security.tss_tx_id.

Missing Signatures

A missing signature on the document does not mean the document is not in compliance with the law (see Punkt 7 AEAO to § 146a). However, the fiskaly API must be implemented in such a way that each transaction requests a signature. If it is not possible to acquire one, the DSFinV-K rules apply.

⚠️Unsigned transactions still need to be recorded

All transactions, including those without a signature, must appear in the DSFinV-K export. For transactions without a signature, all known data is transferred to the DSFinV-K export.

DSFinV-K and Transactions

The financial authorities recommend adding a clear note on the receipt for unsigned transactions, such as:

“TSS not available” or “TSS signing failed”

📘Note

When using the fiskaly DSFinV-K API, the transactions.security.error_message field should be used instead of transactions.security.tss_tx_id at the insertCashPointClosing endpoint in the case of unsigned transactions.

Authorization

Authorization is initially done via API Key and API Secret. You will receive:

Token	Validity
access_token	24 hours
refresh_token	48 hours

You can use these tokens to reauthorize yourself on an ongoing basis. If you receive a 401 response, simply reauthorize via API Key and Secret.

⚠️Don't reauthorize on every request

Reauthorization should not happen on every request, as this would add unnecessary overhead to your checkout process. The validity of the tokens is given for multiple hours.

💡Summary of best practices

1. Set appropriate timeouts for each endpoint type
2. Make timeouts configurable by an administrator
3. Never block the till — always allow the checkout to proceed
4. Record all transactions in the DSFinV-K export, even unsigned ones
5. Add a clear note to receipts when a signature is missing
6. Cache authorization tokens and reuse them within their validity period

Related Pages

New Customers Guide

Complete setup walkthrough including authentication

Support

How to raise an issue and contact the support team