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 Flow	Terminate User Session	Increase Failed Factor Attempts
1	Wrong user input (retry possible)	Sending a wrong password in a Username 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
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.	400	UNEXPECTED_CALL	-	no	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 Factor Attempts
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 Factor Attempts
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 Example 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 Example 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 Example 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 Example Developer Note `FlowStep` returns `StepResultType.EXIT` without error code	-	500	-	-	yes	yes	yes
6	Flow step terminates with an error Example 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