Error Codes and Monitoring
Thanks to bLink's 1:n connectivity, its integration is highly scalable. Scaling the solution also means that there is no direct business relationship between the majority of the Service Providers and Service Users that would allow for immediate coordination and customer support in case of problems with your connectivity enabled service. Hence, automation and a reliable overview of the integration is necessary to efficiently support the end customer throughout the use of your service in your product. Ultimately, the goal is to reduce the number of support touchpoints with the end customer and enable him to take appropriate action on a self-service basis in the event of potential service errors.
To ensure this, the following topics are relevant:
- Generic Error Code: Error Code Handling refers to the process of transmitting generic error codes and subsequent actions to the end customer in a simple and understandable manner.
- Interface Monitoring: Interface Monitoring refers to the practice of observing the service on an operational basis to indicate to end customers and system operators (Sysop, SRE etc.) the availability of the service and whether any action is required.
Both must be focused on serving the end customer to navigate through the Service User’s and the Service Provider’s product. This is important because value is co-created through connectivity (read more about this in the chapter Operational Best Practice).
Generic Error Codes
The following generic error codes can occur when interacting with the APIs on bLink. The table serves as a comprehensive overview with explanations and recommendations for possible error message that can be transmitted to the end customer. Automatic triggers can help streamline operations and proper error message handling improves efficiency for all Service Users and Service Providers by increasing self-service for end customers.
Operational best practice has shown that passing a clear error message to the end customer increases transparency with your support team. You can find out more about support interactions in the section Support Processes in the chapter Operational Best Practice. For cloud-based services, issues often occur globally for all end customers. However, error messages should aim to guide the customer to the right course of action, while the issue can simultaneously be addressed internally or by the bLink team. An example of such an intervention could be an issue with payment transmission. The application user can be advised to try again later while the issue is being addressed internally. Monitoring the system is therefore critical. Find out more about this in the following section Interface Monitoring.
| HTTP Code | Error-Response Examples | User Message Examples (your mileage may vary!) |
|---|---|---|
| 400 Bad Request |
|
|
| 400 Bad Request |
|
|
| 400 Bad Request |
|
|
| 400 Bad Request |
|
|
| 400 Bad Request |
|
|
| 400 Bad Request |
|
|
| 401 Unauthorized |
|
|
| 401 Unauthorized |
|
|
| 403 Forbidden |
|
|
| 404 Not Found |
|
|
| 404 Not Found |
|
|
| 404 Not Found |
|
|
| 405 Not Allowed |
|
|
| 429 Too Many Requests |
|
|
| 500 Technical Errors |
|
|
| 500 Technical Errors |
|
|
| 501 Not Implemented |
|
|
| 502 Bad Gateway |
|
|
| 503 Service Unavailable |
|
|
Consent Management 2.0
| HTTP Code | Error-Response Examples | User Message Examples (your mileage may vary!) |
|---|---|---|
| 401 Unauthorized |
|
|
| 401 Unauthorized |
|
|
Consent Management 2.0 with Consent as a Service
| HTTP Code | Error-Response Examples | User Message Examples (your mileage may vary!) |
|---|---|---|
| 403 Unauthorized |
|
|
| 403 Unauthorized |
|
OAuth2 Error Codes
To complement the bLink error codes, OAuth2 error codes should be utilized in cases where the OAuth2 standard applies.
Relevant parts of the OAuth2 specification regarding the error codes to use can be found here:
- https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1
- https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
- https://datatracker.ietf.org/doc/html/rfc6749#section-7.2
- https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
[The blink system specifies rfc6750 section 3 to the effect that a 401 status code MUST not only SHOULD be returned from the resource in cases where the access token provided is expired, revoked, malformed, or invalid for other reasons. Only if a 401 status code is returned the "Consent-as-a-Service" solution will make an attempt to automatically refresh the access token in this case.]
Interface Monitoring
Interface monitoring through efficient logging of all API requests to ensure the correct triggers is essential for running a successful bLink integration. In order for the logs to be effective and useful, the following should be considered:
- Correlation-IDs need to be transmitted to the logs to ensure traceability of an API call across systems.
- Ensure that the logs can track an application user’s interaction to identify where the user flow failed (e.g. a customer's retrieval of transactions may include authentication steps, retrieval of the list of statements' endpoint, retrieval of the statements, etc.). It is essential to quickly identify the failed API call or endpoint.
Based on the logs, monitoring should be set up with appropriate triggers for end customers and/or system operators. Best practice shows that working with thresholds is most effective (e.g. ff x% of all calls to a bank fail within x hours). The threshold is part of the applicable business logic and should be based on the expected traffic and the covered use cases. In addition, a support process help to handle issues quickly and efficiently to reduce the impact on all Service Users and Service Providers. For more process information, see the section Support Processes in the chapter Operational Best Practice.
In order for logs to be shareable and most effective, they must adhere to use case relevant data security requirements. Client Identifying Data (CID) should never be part of the logs and must be avoided.