16.8. Flow error handling

Flows do not always complete successfully. Errors can either result from wrong user input or from unexpected application behavior. The following tables gives an overview of error cases and how the REST API represents them.

Please refer to the REST API specifications for an exact description of the HTTP response and error codes of individual calls.

User/client errors

#
Description
Example
HTTP Response Status
Error Code
Next Step
Terminate Authentication Flow
Terminate User Session
Increase Failed Logins
1
Wrong user input (retry possible)
Sending a wrong password in a password authentication step - retries are allowed.
400
Flow step specific, e.g. USERNAME_PASSWORD_WRONG
Flow step specific, e.g. PASSWORD_REQUIRED
no
no
yes
Exceptions:
A password policy failure during a mandatory password change will not increase failed logins.
2
Wrong user input (no retry possible)
Sending the wrong mTAN OTP too many times.
403
Flow step specific, e.g. MTAN_OTP_WRONG
-
yes
no
yes
3
Wrong user input that terminates the session
The user is locked because of too many failed inputs.
403
E.g. USER_LOCKED
-
yes
yes
yes
4
The user/client sends an unexpected request that does not match the state of the flow
The user sends the password although an mTAN OTP is required.
403
UNEXPECTED_CALL
-
yes
no
yes
5
The client makes concurrent authentication requests
-
400
CONCURRENT_ACCESS
-
no
no
no

Flow errors

#
Description
Example
HTTP Response Status
Error Code
Next Step
Terminate Authentication Flow
Terminate User Session
Increase Failed Logins
1
Tag expires during a flow
The user authenticated for application 'A' with username/password and obtained the tag 'PWD'. This tag has a lifetime of 60 minutes.
After 59 minutes, the user does a step up for application 'B' which requires the tag 'PWD'. The step-up flow takes 2 minutes and the 'PWD' tag expired.
403
FLOW_SESSION_EXPIRED
-
yes
no
no
2
Unconsumed red flags in the flow session at the end of a flow
The password step demands a mandatory password change to be done in the flow but none occurred.
500
-
-
yes
yes
yes

Step errors

#
Description
Example
HTTP Response Status
Error Code
Next Step
Terminate Authentication Flow
Terminate User Session
Increase Failed Logins
1
Flow step fails due to violated precondition
The user session does not have all the required tags for the next step.
500
-
-
yes
yes
yes
2
Flow step fails directly

Developer Note

initialize() of a FlowStep returns StepResultType.FAIL

Flow steps such as 'Required Role' directly fail if their condition is not met.
403
Flow step specific, e.g. USER_ROLE_MISSING
-
yes
no
yes
3
Flow step fails directly

Developer Note

initialize() of a FlowStep returns StepResultType.FAIL_RETRY

This is not a valid use-case but might happen in the wrong custom code implementations. It does not make sense to directly fail with retry because additional user input is not possible in such a step.
500
-
-
yes
yes
yes
4
Flow steps (or services) have an error because of an unexpected state

Developer Note

ViolationException in a step or service results in StepResultType.FAIL

The user selects an mTAN Token although a token is already selected.
403
Flow step specific
-
yes
no
yes
5
Flow step terminates without error

Developer Note

FlowStep returns StepResultType.EXIT without error code

-
500
-
-
yes
yes
yes
6
Flow step terminates with an error

Developer Note

FlowStep returns StepResultType.EXIT with an error code

-
403
Flow step specific
-
yes
yes
yes
7
Flow step or flow processor has an unexpected error
Unexpected technical problem in a flow step, e.g. no access to persistency.
500
-
-
yes
yes
yes

Further information and links