Handling errors

Using a service isn’t always successful: users enter wrong credentials, upstream systems have technical issues and so on. How these errors show up in detail depends on the client SDK, i.e. which language is used. Generally, your application needs to handle these errors. Following is a list of possible errors, what they mean and some guidance what your application could do to handle them.

In general, with the exception of a RequestError, any error leaves the service in a failed state. This means you cannot continue it with any of the respond or confirm methods and need to start it again, with a new ticket (see also Getting Started).

Some errors carry a user message: a human-readable text originating from the bank that describes the problem in terms meaningful to the end user (for example, why access was blocked). Where present, prefer showing it to the user over a generic message. The guidance below refers to it as the user message field.

For the payment services (Collect Payment and Transfer), an UnexpectedError or ProviderError does not mean the payment failed: it may still have been executed. Do not automatically re-initiate the payment, as that risks a duplicate. Check whether the funds arrived before starting a new one.

Name Description What to do Services

Name	Description	What to do	Services
`RequestError` `RequestException`	The SDK couldn’t execute the request, e.g. due to a network issue.	Retry the request. The JavaScript SDK allows to set a retry policy, so failing requests are automatically retried.	any
`UnexpectedError` `UnexpectedErrorException`	An upstream service (e.g. a bank’s API) responded in a way that is not processible. This can have many reasons (e.g. technical issues on their end or some API not conforming to a specification). Please note that observing this error doesn’t necessarily mean that the service failed. E.g. for the Collect Payment service, it is still possible that the transaction is executed.	Inform the user that a technical error has happened. Show the user message field if present. We would appreciate it if you can send us a Diagnostic archive whenever this happens, so you can also prompt the user whether they want to share diagnostics with us.	any
`Canceled` `CanceledException`	The user has canceled the transaction (e.g. by rejecting a SCA) or a timeout has occurred and it’s no longer possible to complete the transaction.	Ask if the user wants to start again.	any
`InvalidCredentials` `InvalidCredentialsException`	The credentials were not accepted. This is usually a wrong password or TAN, but the bank may also return it when access is (temporarily) locked. The user message field, if present, carries the bank’s specific reason.	Show the user message field if present, as it states the actual reason. Only if it is absent, prompt the user to check their credentials. If you see this error frequently, it is worth reviewing how your login form collects credentials against Providing Credentials, as credential-entry issues in the frontend are a common cause.	any
`ServiceBlocked` `ServiceBlockedException`	An upstream service indicated that the service is blocked for this specific user. This could mean that the user needs to do some action with the provider, e.g. change a password or accept some newer terms of service or that the account itself is blocked. `code` contains an optional reason why the service is blocked.	Show the user message field if present. Otherwise, evaluate `code` if present and show a generic message based on that.	any
`Unauthorized` `UnauthorizedException`	Invalid or expired consent. Only happens if you provide connection data and use recurring consents. This error will be handled automatically at some point in the future.	Restart the service without passing connection data.	any
`AccessExceeded` `AccessExceededException`	Access to the account has been exceeding the user’s consent. Should not happen in interactive service usages.		`Accounts`, `Balances`, `Transactions`, `StandingOrders`
`PeriodOutOfBounds` `PeriodOutOfBoundsException`	Requested time period is out of bounds.	Display the user message field if present.	`Transactions`
`UnsupportedProduct` `UnsupportedProductException`	The requested operation could not be performed because it isn’t supported. Examples for this are when an instant payment was requested, but isn’t supported or when a connection was used with a service that doesn’t support it. See also Instant by default.	Display the user message field if present.	any
`PaymentFailed` `PaymentFailedException`	The bank indicated that the payment has failed, e.g. due to an exceeded limit. The error has an optional machine-readable `code` field for the reason.	Display the user message field if present.	`CollectPayment`, `Transfer`
`UnexpectedValue` `UnexpectedValueException`	An unexpected value was passed, e.g. a malformed IBAN. The error has an `error` field that explains why the value is unexpected. This error is meant for the application developer.	Add validation if data is passed from users.	any
`TicketError` `TicketException`	Something was wrong with the ticket that was used for the service call (e.g. the ticket has expired, or a wrong key was used). The error also has a `code` field that contains the machine-redable reason.	Evaluate the `code`. If it’s `Expired`, notify your user that they took too long to finish the process and start again. Any other code means a configuration error in your app.	any
`ProviderError` `ProviderErrorException`	An upstream service indicated that a request failed due to technical reasons (including maintenance). Please note that observing this error doesn’t necessarily mean that the service failed. E.g. for the Collect Payment service, it is still possible that the transaction is executed.	Display to the user that a technical error has occurred and that they might retry at a later point.	any
`ResponseError` `ResponseException`	The SDK couldn’t handle a service response. This is generally unexpected and either indicates a bug or an outdated SDK.	Display to the user that a technical error has occurred. Report internally and investigate if this happens frequently.	any
`NotFound` `NotFoundException`	During a `Transactions` or `StandingOrders` service, it means that the given account couldn’t be found.	For `Transactions` and `StandingOrders`: check the account reference that your app passed.	`Transactions`, `StandingOrders`, `info` call, `trace` call
`InterruptError` `InterruptErrorException`	The service requires user interaction to complete, but was called with connection data instead of credentials.	Start the service again with credentials when the user is available and store the connection data it returns.	any

RequestError
RequestException

The SDK couldn’t execute the request, e.g. due to a network issue.

Retry the request. The JavaScript SDK allows to set a retry policy, so failing requests are automatically retried.

any

UnexpectedError
UnexpectedErrorException

An upstream service (e.g. a bank’s API) responded in a way that is not processible. This can have many reasons (e.g. technical issues on their end or some API not conforming to a specification).
Please note that observing this error doesn’t necessarily mean that the service failed. E.g. for the Collect Payment service, it is still possible that the transaction is executed.

Inform the user that a technical error has happened. Show the user message field if present. We would appreciate it if you can send us a Diagnostic archive whenever this happens, so you can also prompt the user whether they want to share diagnostics with us.

any

Canceled
CanceledException

The user has canceled the transaction (e.g. by rejecting a SCA) or a timeout has occurred and it’s no longer possible to complete the transaction.

Ask if the user wants to start again.

any

InvalidCredentials
InvalidCredentialsException

The credentials were not accepted. This is usually a wrong password or TAN, but the bank may also return it when access is (temporarily) locked. The user message field, if present, carries the bank’s specific reason.

Show the user message field if present, as it states the actual reason. Only if it is absent, prompt the user to check their credentials. If you see this error frequently, it is worth reviewing how your login form collects credentials against Providing Credentials, as credential-entry issues in the frontend are a common cause.

any

ServiceBlocked
ServiceBlockedException

An upstream service indicated that the service is blocked for this specific user. This could mean that the user needs to do some action with the provider, e.g. change a password or accept some newer terms of service or that the account itself is blocked. code contains an optional reason why the service is blocked.

Show the user message field if present. Otherwise, evaluate code if present and show a generic message based on that.

any

Unauthorized
UnauthorizedException

Invalid or expired consent. Only happens if you provide connection data and use recurring consents. This error will be handled automatically at some point in the future.

Restart the service without passing connection data.

any

AccessExceeded
AccessExceededException

Access to the account has been exceeding the user’s consent. Should not happen in interactive service usages.

Accounts, Balances, Transactions, StandingOrders

PeriodOutOfBounds
PeriodOutOfBoundsException

Requested time period is out of bounds.

Display the user message field if present.

Transactions

UnsupportedProduct
UnsupportedProductException

The requested operation could not be performed because it isn’t supported. Examples for this are when an instant payment was requested, but isn’t supported or when a connection was used with a service that doesn’t support it.
See also Instant by default.

Display the user message field if present.

any

PaymentFailed
PaymentFailedException

The bank indicated that the payment has failed, e.g. due to an exceeded limit. The error has an optional machine-readable code field for the reason.

Display the user message field if present.

CollectPayment, Transfer

UnexpectedValue
UnexpectedValueException

An unexpected value was passed, e.g. a malformed IBAN. The error has an error field that explains why the value is unexpected. This error is meant for the application developer.

Add validation if data is passed from users.

any

TicketError
TicketException

Something was wrong with the ticket that was used for the service call (e.g. the ticket has expired, or a wrong key was used). The error also has a code field that contains the machine-redable reason.

Evaluate the code. If it’s Expired, notify your user that they took too long to finish the process and start again. Any other code means a configuration error in your app.

any

ProviderError
ProviderErrorException

An upstream service indicated that a request failed due to technical reasons (including maintenance).
Please note that observing this error doesn’t necessarily mean that the service failed. E.g. for the Collect Payment service, it is still possible that the transaction is executed.

Display to the user that a technical error has occurred and that they might retry at a later point.

any

ResponseError
ResponseException

The SDK couldn’t handle a service response. This is generally unexpected and either indicates a bug or an outdated SDK.

Display to the user that a technical error has occurred. Report internally and investigate if this happens frequently.

any

NotFound
NotFoundException

During a Transactions or StandingOrders service, it means that the given account couldn’t be found.

For Transactions and StandingOrders: check the account reference that your app passed.

Transactions, StandingOrders, info call, trace call

InterruptError
InterruptErrorException

The service requires user interaction to complete, but was called with connection data instead of credentials.

Start the service again with credentials when the user is available and store the connection data it returns.

any