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 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

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