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).

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).	Inform the user that a technical error has happened. Show `user_message` to the user 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 user entered wrong credentials. This can also be a wrong TAN input.	Display to the user that the entered credentials were wrong. Show `user_message` to the user if present.	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 `user_message` to the user if present. Otherwise, evaluate `code` if present and show a generic message based on that.	any
`Unauthorized` `UnauthorizedException`	Invalid 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
`ConsentExpired` `ConsentExpiredException`	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.		`Transactions`
`PeriodOutOfBounds` `PeriodOutOfBoundsException`	Requested time period is out of bounds.	Display `user_message` to the user 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 `user_message` to the user if present.	any
`PaymentFailed` `PaymentFailedException`	The bank indicated that the payment has failed, e.g. due to an exceeded limit. The erros has an optional machine-readable `code` field for the reason.	Display `user_message` to the user if present.	`CollectPayment`
`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).	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` service, it means that the given account couldn’t be found.	For `Transactions`: check the account reference that your app passed.	`Transactions`, `info` call, `trace` call

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).

Inform the user that a technical error has happened. Show user_message to the user 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 user entered wrong credentials. This can also be a wrong TAN input.

Display to the user that the entered credentials were wrong. Show user_message to the user if present.

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 user_message to the user if present. Otherwise, evaluate code if present and show a generic message based on that.

any

Unauthorized
UnauthorizedException

Invalid 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

ConsentExpired
ConsentExpiredException

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.

Transactions

PeriodOutOfBounds
PeriodOutOfBoundsException

Requested time period is out of bounds.

Display user_message to the user 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 user_message to the user if present.

any

PaymentFailed
PaymentFailedException

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

Display user_message to the user if present.

CollectPayment

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).

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 service, it means that the given account couldn’t be found.

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

Transactions, info call, trace call