Error handling

All responses from the Consent API with a response code >=400 should be handled as an error with the format described in this section. Beside the most common consent errors as described below there is also a list of common error codes that should be considered for error handling.

{
    "error": {
        "code": String,
        "message": String
    },
    "consent_token": ?String,
    "transfer_token": ?String
}

Avoiding early Consent Invalidation

Consent errors can also occur due to temporary issues at the bank. The same request resulting in an error at first might be successful in a second attempt. The underlying consent represented by the latest consent_token remains valid in these cases.

There is no specific error response which indicates such a temporary issue at the bank but any error response can be caused by this except for CONSENT.LIMIT_EXCEEDED. This means a response might contain the CONSENT.EXPIRED error while the consent is actually not expired but was rejected from the bank due to an issue.

As a result, we recommend to ignore the first error response and repeat the request at a later point in time, ideally one day but at least 30 minutes after the first error response. A possible second error response can then be treated as final.

Example Error Responses

A general error occurred when using a consent

HTTP 400 Bad Request

{
    "error": {
        "code": "CONSENT",
        "message": "A general error when using a consent that can not be specified in detail"
    }
}

The consent for a used token has expired

HTTP 400 Bad Request

{
    "error": {
        "code": "CONSENT.EXPIRED",
        "message": "The consent lifetime has expired"
    }
}

The consent has been revoked

HTTP 400 Bad Request

{
    "error": {
        "code": "CONSENT.REVOKED",
        "message": "The consent has been revoked"
    }
}

The limit for daily usage of this consent has been exceeded

HTTP 400 Bad Request

{
    "error": {
        "code": "CONSENT.LIMIT_EXCEEDED",
        "message": "The daily limit of the consent usage has been exceeded"
    }
}

Request not supported by bank

HTTP 400 Bad request

{
    "error": {
        "code": "NOT_SUPPORTED.TRANSACTIONS_DATE_RANGE",
        "message": "The requested date range is not supported for this bank"
    },
    "consent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjEyMzQ1Njc4OTAifQ.na71ipK8ASvggoM6C5vMjBKgJlZLxV-m6ElgHBrNtlU"
}

The provided payload to fetch a consent is invalid

HTTP 400 Bad request

{
    "error": {
        "code": "badRequest",
        "message": "'account_id' is missing"
    }
}

A token can not be requested for a session which is not logged in or does not exists

HTTP 404 Not found

{
    "error": {
        "code": "notFound",
        "message": "Could not request a consent token for a session which is not logged in"
    }
}

Any unexpected error

HTTP 500 Internal Server Error

{
    "error": {
        "code": "internalServerError",
        "message": "Internal Server Error"
    }
}