These docs are for v2.11. Click to read the latest docs for v2.13.

Errors

If an error occurs during a request, the API returns an HTTP status code >=400 and provides more
information in the response-body.

Error Object Structure

FieldDescription
codeNumeric representation of the error. See Error Codes.
dataAdditional error information (validation information and other details)
descriptionShort summary
groupThe group to which this error is associated to. See Error Codes.
messageOriginal message of the bank (only in task errors)

Examples:

{
  "error": {
    "code": 1000,
    "data": {
      "bank_code": ["Not a valid string."],
      "credentials": ["Credentials must contain at least 2 strings."]
    },
    "description": "Request body doesn't match input schema.",
    "group": "client"
  }
}
{
  "error": {
    "code": 1002,
    "data": {},
    "description": "Not Found",
    "group": "client",
  }
}

Error Codes

Error codes are grouped in ranges

RangeGroup
1000 - 1999client
10000 - 19999user
20000 - 29999bank
30000 - 39999general
40000 - 49999connectivity
50000 - 59999categorization

whereas each code has the following meaning

CodeGroupDescription
1000clientInvalid request
1001clientEntry already exists
1002clientEntity not found
1003clientUnauthorized
1004clientInvalid client authorization
1005clientPayment already processed
1006clientUnprocessable entity
1007clientForbidden
1008clientResource busy
1010clientUser locked
1011clientLogin credentials are incomplete or malformed
1020clientMaximum number of account synchronizations exceeded
1021clientPSU IP is required
10000userLogin credentials are invalid
10001userPIN is invalid
10002userOnline access is blocked
10003userTAN scheme not activated
10004userTAN is invalid
10005userNo authorization for this account
10006userTransaction rejected
10007userPIN change necessary
10008userNo authorization for this business transaction
10009userHBCI activation necessary
10010userAccount is blocked
10011userAccount no longer exists
10012userTAN scheme is blocked
10013userStatus of transaction inconclusive
10014userAccount not activated for online banking
10015userRedundant submissions
10016userInvalid OTP
10017userInvalid consent configuration
11000userGeneric user error
20000bankProcessing at the bank not possible
20001bankBank / account unknown
20002bankTransaction canceled
20003bankMaintenance
20004bankTechnical migration
20005bankTransaction not possible
20006bankLogin not possible
20007bankPop up
30000generalProcessing at finX not possible
30005generalTask is expired
30006generalService temporarily not available
40000generalBank not supported
40001generalDirect access upgrade
40002generalMulti-access upgrade
40003generalPartial access upgrade

Resource locked

With ongoing improvements on our system, at any point, a resource might return the HTTP status code 423 and the error code 1008. Your application should implement a retry logic with incremental backoff in the realm of seconds and up to minutes.

The most likely scenario where this happens is after a version change that requires data migration. The first request to an unmigrated user would then trigger such a response, consecutive calls might return 423 until migration is done.