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.
# | 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 |
# | 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 |
# | 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
| 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
| 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
| 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
| - | 500 | - | - | yes | yes | yes |
6 | Flow step terminates with an error Developer Note
| - | 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 |