Skip to main content

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 CodeError-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

HTTP CodeError-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

HTTP CodeError-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:

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.