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:

1. 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.
2. 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 the 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.

** Important ** bLink always sends error responses with the header attribute 'Content-Type' set to 'application/problem+json', regardless of the expected response format, even in cases like 'application/xml'. Please ensure your system is configured to accept 'application/problem+json' as a valid response content type.

HTTP Code	Error-Response Examples	User Message Examples (your mileage may vary!)
400 Bad Request	Type /problems/INVALID_PAYLOAD Title The payload was not valid Detail ID is missing.	User Message AIS We couldn't retrieve any transactions. Please try again later. [400 INVALID_PAYLOAD] User Message PSS We couldn't transmit any payment orders. Please try again later. [400 INVALID_PAYLOAD]
400 Bad Request	Type /problems/MALFORMED_PAYLOAD Title Payload does not comply with API specification Detail Malformed JSON.	User Message AIS We couldn't retrieve any transactions. Please try again later. [400 MALFORMED_PAYLOAD] User Message PSS We couldn't transmit any payment orders. Please try again later. [400 MALFORMED_PAYLOAD]
400 Bad Request	Type /problems/MALFORMED_PAYLOAD Title Invalid parameter values have been detected Detail Data for date in the future cannot be requested.	User Message AIS We couldn't retrieve any transactions. Please try again later. [400 MALFORMED_PAYLOAD] User Message PSS We couldn't transmit any payment orders. Please try again later. [400 MALFORMED_PAYLOAD] Hint Don’t allow future payments in your requests
400 Bad Request	Type /problems/RESOURCE_TOO_LARGE Title Generated resource was too large Detail The generated resource exceeded the size limit	User Message AIS We couldn't retrieve any transactions. Please try again later. [400 RESOURCE_TOO_LARGE] User Message PSS We couldn't transmit any payment orders. Please try again later. [400 RESOURCE_TOO_LARGE] Hint If a date filter is available, direct the customer to use the date filter. Or direct the user to transmit payments in multiple batches
400 Bad Request	Type /problems/INVALID_PAYLOAD Title JSON not Valid Detail scope: must not be null	User Message AIS We couldn't retrieve any transactions. Please try again later. [400 INVALID_PAYLOAD] User Message PSS We couldn't transmit any payment orders. Please try again later. [400 INVALID_PAYLOAD]
400 Bad Request	Type /problems/INVALID_PAYLOAD Title JSON not Valid Detail username: must not be null	User Message AIS We couldn't retrieve any transactions. Please try again later. [400 MALFORMED_PAYLOAD] User Message PSS We couldn't transmit any payment orders. Please try again later. [400 MALFORMED_PAYLOAD]
401 Unauthorized	Type /problems/INVALID_TOKEN Title The OAuth Token is invalid Detail Something is wrong with this token.	User Message AIS Bank transactions couldn't be retrieved due to lack of authentication. Please disconnect the connection and reconnect your bank account. [401 INVALID_TOKEN] User Message PSS Payment orders couldn't be transmitted due to lack of authentication. Please disconnect the connection and reconnect your bank account. [401 INVALID_TOKEN] Hint Automatically disconnect user and direct the user to the connect flow
401 Unauthorized	Type /problems/EXPIRED_TOKEN Title The OAuth Token is expired Detail The token is no longer valid.	User Message AIS Bank transactions couldn't be retrieved due to lack of authentication. Please disconnect the connection and reconnect your bank account. [401 EXPIRED_TOKEN] User Message PSS Payment orders couldn't be transmitted due to lack of authentication. Please disconnect the connection and reconnect your bank account. [401 EXPIRED_TOKEN] Hint Automatically disconnect user and direct the user to the connect flow
403 Forbidden	Type /problems/INSUFFICIENT_PRIVILEGES Title No privileges for the requested operation Detail Insufficient privileges for the requested operation.	User Message AIS Bank transactions couldn't be retrieved due to lack of authentication. Please disconnect the connection and reconnect your bank account. [403 INSUFFICIENT_PRIVILEGES] User Message PSS Payment orders couldn't be transmitted due to lack of authentication. Please disconnect the connection and reconnect your bank account. [403 INSUFFICIENT_PRIVILEGES] Hint Automatically disconnect user and direct the user to the connect flow
404 Not Found	Type /problems/TECHNICAL_ERROR Title URL not found Detail The requested endpoint does not exist	User Message AIS We couldn't retrieve any transactions. Please try again later. [404 TECHNICAL_ERROR] User Message PSS We couldn't submit the payment orders. Please try again later. [404 TECHNICAL_ERROR]
404 Not Found	Type /problems/NOT_IMPLEMENTED Title Feature is not implemented Detail This interface does not support intraday data	User Message AIS The bank does not allow retrieving transaction. Please contact your bank to resolve the issue. [404 NOT_IMPLEMENTED] User Message PSS The bank does not allow the submission of payments. Please contact your bank to resolve the issue. [404 NOT_IMPLEMENTED] Hint Only if the limiting factor is the service provider.
404 Not Found	Type /problems/INSUFFICIENT_PRIVILEGES Title Insufficient privileges to access resource Detail The provided token does not grant access to the requested resources	User Message AIS Bank transactions couldn't be retrieved due to lack of privileges. Please disconnect the connection and reconnect your bank account. [404 INSUFFICIENT_PRIVILEGES] User Message PSS Payment orders couldn't be transmitted due to lack of privileges. Please disconnect the connection and reconnect your bank account. [404 INSUFFICIENT_PRIVILEGES] Hint Automatically disconnect user and direct the user to the connect flow
405 Not Allowed	Type /problems/WRONG_METHOD Title This HTTP Operation is not allowed on this endpoint Detail Only GET operations are allowed.	User Message AIS We couldn't retrieve any transactions. Please try again later. [405 WRONG_METHOD] User Message PSS We couldn't submit the payment orders. Please try again later. [405 WRONG_METHOD]
429 Too Many Requests	Type /problems/TECHNICAL_ERROR Title Rate Limit Exceeded	User Message AIS We couldn't perform the operation [e.g. connect your bank accounts]. Please try again [429 RATE_LIMITING_ERROR] User Message PSS We couldn't perform the operation [e.g. submit payments]. Please try again [429 RATE_LIMITING_ERROR] Hint Error code messages are only relevant if the corresponding monitoring has been implemented.
500 Technical Errors	Type /problems/TECHNICAL_ERROR Title Technical error on server side Detail Processing yielded a technical error.	User Message AIS Connection to your bank account could not be established. In urgent cases, please upload the transaction files manually or try again later. [500 TECHNICAL_ERROR] User Message PSS The bank's API can currently not be reached for this operation. In urgent cases, please download the payment file manually or try again later. [500 TECHNICAL_ERROR]
500 Technical Errors	Type /problems/RESOURCE_TOO_LARGE Title Generated resource was to large Detail The generated resource exceeded the size limit.	User Message AIS We couldn't retrieve any transactions. Please get in touch with our support. [500 RESOURCE_TOO_LARGE] User Message PSS We couldn't transmit any payment orders. Please get in touch with our support. [500 RESOURCE_TOO_LARGE] Hint If a date filter is available, direct the customer to use the date filter. Or direct the user to transmit payments in multiple batches
501 Not Implemented	Type /problems/NOT_IMPLEMENTED Title Not Implemented Detail This feature/endpoint is not implemented.	User Message AIS The bank does not allow retrieving transaction. Please contact your bank to resolve the issue. [501 NOT_IMPLEMENTED] User Message PSS The bank does not allow the submission of payments. Please contact your bank to resolve the issue. [501 NOT_IMPLEMENTED] Hint Only if the limiting factor is the service provider.
502 Bad Gateway	Type /problems/TECHNICAL_ERROR Title Invalid response from upstream system Detail The response received from the upstream server was invalid (e.g. malformed headers or payload) and could not be processed.	Hint testing environment Upstream system did not return a valid or expected response format. Check the payload of the response returned. Hint production environment Upstream system did not return a valid or expected response format. The Service Provider will be informed about the issue and asked to investigate and correct the payload.
503 Service Unavailable	Type /problems/TECHNICAL_ERROR Title This is the general problem description Detail Detailed problem description with respect to the current request, e.g., invalid account number format.	User Message AIS Bank transactions couldn't be retrieved. Please disconnect the connection and reconnect your bank account. [503 TECHNICAL_ERROR] User Message PSS Payment orders couldn't be transmitted. Please disconnect the connection and reconnect your bank account. [503 TECHNICAL_ERROR] Hint Automatically disconnect user and direct the user to the connect flow

Consent Management 2.0

HTTP Code	Error-Response Examples	User Message Examples (your mileage may vary!)
401 Unauthorized	Type /problems/INVALID_TOKEN Title The OAuth Token is invalid Detail Something is wrong with this token.	User Message Bank connection couldn’t be established due to lack of authentication. Please disconnect the connection and reconnect your bank account. [401 INVALID_TOKEN] Hint Automatically disconnect user and direct the user to the connect flow
401 Unauthorized	Type /problems/EXPIRED_TOKEN Title The OAuth Token is expired Detail The token is no longer valid.	User Message Bank connection couldn’t be established due to lack of authentication. Please disconnect the connection and reconnect your bank account. [401 EXPIRED_TOKEN] Hint Automatically disconnect user and direct the user to the connect flow

Consent Management 2.0 with Consent as a Service

HTTP Code	Error-Response Examples	User Message Examples (your mileage may vary!)
403 Unauthorized	Type /problems/EXPIRED_TOKEN Title The OAuth Token is invalid Detail Something is wrong with this token.	User Message Bank connection couldn’t be established due to lack of authentication. Please disconnect the connection and reconnect your bank account. [403 EXPIRED_TOKEN] Hint Automatically disconnect user and direct the user to the connect flow
403 Unauthorized	Type /problems/INSUFFICIENT_PRIVILEGES Title Access denied Detail Access not allowed for specified permission	User Message Bank connection couldn’t be established due to lack of privileges. Please disconnect the connection and reconnect your bank account. [403 INSUFFICIENT_PRIVILEGES] Hint Automatically disconnect user and direct the user to the connect flow

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:

1. Correlation-IDs need to be transmitted to the logs to ensure traceability of an API call across systems.
2. 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.

Sensitive Information

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.