Authentication Requirements v2.12 min read
This page defines the required error handling behaviour when the end user fails to authenticate during the consent journey. The LFI MUST invoke POST /auth/{interactionId}/doFail with the exact error and error_description values specified below.
For the full doFail API specification, see the POST /auth/{interactionId}/doFail API Reference.
Error scenarios
1. End user fails initial authentication
The end user does not successfully complete initial authentication — for example, by exceeding the maximum number of allowed attempts (e.g. 3 failed attempts).
erroraccess_deniederror_descriptionuser_failed_to_authenticateThe LFI MUST NOT PATCH the consent to Rejected in this scenario — the end user's identity has not been confirmed, so no end user identifiers are available.
2. End user fails step-up authentication
The end user authenticated successfully during initial login but fails the step-up authentication required for payment consent confirmation — for example, failing biometric verification or exceeding the maximum number of step-up attempts.
erroraccess_deniederror_descriptionuser_failed_step_up_authenticationThe LFI MUST PATCH the consent to Rejected before calling doFail — the end user was already identified during initial authentication.
3. End user is blocked, suspended, or flagged
The end user authenticates successfully but the LFI determines the customer account is blocked, suspended, or otherwise flagged — for example, due to a fraud hold, deceased marker, or sanctions screening.
erroraccess_deniederror_descriptionuser_account_blockedThe LFI MUST NOT PATCH the consent to Rejected in this scenario — the LFI SHOULD NOT associate the consent with a blocked account in the API Hub.
4. LFI internal technical error
The LFI encounters an internal technical error during the authentication process — for example, an internal service failure or inability to retrieve customer data.
errorserver_errorerror_descriptionlfi_internal_errorThe LFI MUST NOT PATCH the consent to Rejected — the end user's identity may not have been confirmed, and the failure is not attributable to the end user.
5. LFI fails to communicate with API Hub
GET /auth fails, the LFI has no interactionId and therefore cannot call doFail. In this case the LFI MUST render an error page to the end user explaining that the service is temporarily unavailable.The LFI cannot communicate with the API Hub after the initial GET /auth call — for example, a failure when calling GET /consents/{consentId} to retrieve the consent details.
errorserver_errorerror_descriptionapi_hub_communication_errorThe LFI MUST NOT PATCH the consent to Rejected — the API Hub may be unreachable.
6. LFI temporarily unavailable
The LFI cannot complete authentication due to high load or temporary capacity constraints at the LFI's systems.
errortemporarily_unavailableerror_descriptionlfi_temporarily_unavailableThe LFI MUST NOT PATCH the consent to Rejected — the end user's identity may not have been confirmed.
Summary
error code that is not supported by the FAPI 2.0 Security Profile, the API Hub will overwrite it with invalid_request.access_denieduser_failed_to_authenticateaccess_denieduser_failed_step_up_authenticationaccess_denieduser_account_blockedserver_errorlfi_internal_errorserver_errorapi_hub_communication_errortemporarily_unavailablelfi_temporarily_unavailable