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.

NOTE: If the error response contains a consent token use this token for the next upcoming retry call. Do not use the outdated token.

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

error.code String, always present

The code property indicates the type of the error.

error.message String, always present

The message property holds detailed information about the error provided by the bank's API.

consent_token String, optional

The consent_token property holds the token that could be used for another attempt. It's not present if the token is expired or could not be used again.

transfer_token String, optional

The transfer_token property holds the token that could be used for another attempt. It's only present after a transfer-state call.

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

HTTP 400 Bad Request
{
    "error": {
        "code": "CONSENT",
        "message": "A general error when using a consent that can not be specified in detail"
    }
}
HTTP 400 Bad Request
{
    "error": {
        "code": "CONSENT.EXPIRED",
        "message": "The consent lifetime has expired"
    }
}
HTTP 400 Bad Request
{
    "error": {
        "code": "CONSENT.REVOKED",
        "message": "The consent has been revoked"
    }
}
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"
}
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"
    }
}

results matching ""

    No results matching ""