Error handling

Exceptions categories

In Kontomatik APIs, we can distinguish four types of exceptions:

1. Integration errors
2. Errors caused by external factors beyond Kontomatik’s control
3. User actions
4. Bugs in the Kontomatik system

Errors can occur in two places: as a response from the API or within the onError callback of the Widget.

• API Errors: These are returned as an exception element containing the error name and a message.
• Widget Errors: The onError callback provides the exception name along with an options object, which includes details such as the selected bank and sessionId.

Notably, in the case of the Widget, all errors are managed by Kontomatik. This ensures that the end-user receives appropriate feedback about what went wrong, along with a relevant error message.

To identify a specific exception, refer to the Error List in the documentation, which categorizes exceptions and provides detailed descriptions of each error. Keep in mind that this list is dynamic and may change over time, with new errors potentially being added.

Integration errors

This error category indicates that the issue is caused by incorrect integration with the Kontomatik API. If you encounter such an error while handling the API, you should review your integration and adjust it according to the documentation. If you cannot diagnose the problem on your end, you can contact our support team, which can assist you in identifying the cause of the issue. Additionally, we provide integration examples that can help you create a proper integration with our API.

External errors

This category is reserved for exceptions beyond Kontomatik’s control. When encountering an exception in this category, it is recommended to retry the operation after some time.

For instance, an external error may occur if the selected bank’s API is temporarily unavailable due to maintenance. You can check the status of Kontomatik supported banks at status.kontomatik.com.

User actions

This category is reserved for errors resulting from end-user actions. Most of these errors are not returned by the API but are instead handled in the SignIn Widget onError callback. Kontomatik provides user-friendly messages for these errors directly in the widget, so handling each one individually is unnecessary - and strongly discouraged.

PDF validation errors

This category is reserved for exceptions occurring during validation of a PDF document. It indicates which part of the validation failed to match any of the currently known patterns. This may suggest a potential modification attempt on the document or, in rare cases, that the bank has introduced a new document template that Kontomatik has yet to support.

Bugs in the Kontomatik system

When an exception does not fit any of the above categories, it is classified as a generic exception called KontoXBug.

This most commonly occurs when a bank API behaves in a way that the Kontomatik system could not anticipate. It may also happen due to internal issues within our application or infrastructure.

Kontomatik continuously monitors the occurrence of KontoXBug errors, and, when anomalies are detected, an appropriate fix or response is issued. If you receive such an error, it’s best to retry after some time. If the issue persists, we suggest reporting it to our support team for further investigation.

Reporting problems

In case you encounter persistent issues with the Kontomatik API, particularly with errors that cannot be resolved by retrying or adjusting your integration, you may need to report the problem to the Kontomatik support team. Below is a guide on when and how to report issues effectively.

To streamline troubleshooting, consider customizing your integration to log responses, messages, and session IDs for both the API and the widget whenever an error occurs.

When to report an issue

You should consider reporting an issue to Kontomatik support if:

• Integration errors persist despite following the documentation and troubleshooting on your end.
• External errors continue after multiple retry attempts and appear to be affecting your operations significantly.
• PDF validation errors arise for multiple users, suggesting the need for a potential update to the Kontomatik supported document patterns.
• KontoXBug are encountered and they do not get resolved after retrying or over time.

How to report an issue

To streamline the troubleshooting process and get quicker assistance, ensure that your report includes as much relevant detail as possible. Follow these steps:

Prepare necessary details:

• Session information: Include the sessionId or commandId associated with the problematic session so that Kontomatik team can locate it for analysis, regardless of whether the error occurred in the SignIn Widget or on the API side.
• For API errors: Provide the response content from the API. Ensure that any sensitive information is masked to comply with privacy standards.
• For SignIn Widget errors: Describe the sequence of the end-user actions that led to the error. If possible, include screenshots or a video recording of the process.

Please remember to report issues from different banks separately. This will help Kontomatik support associate errors more efficiently and reduce the risk of overlooking any report.

Submit your report to support@kontomatik.com. Our support team will respond as quickly as possible with an analysis or additional questions. Please note that support is available on weekdays from 9 am to 5 pm CET.