remainingOTPAttempts Condition
In your flow, check the remainingOTPAttempts dynamic value to see how many OTP attempts a user has left. Descope returns the same action error whether a user mistypes the code once or exhausts every attempt, remainingOTPAttempts is what lets you tell the two apart, so you can warn users as they approach the limit.
Descope sets remainingOTPAttempts to your configured limit when it sends the OTP, decrements it after each incorrect attempt, and clears it to an empty value on lockout. It's only populated for OTP sent by email, SMS, voice, WhatsApp, or instant message — for any other authentication method, the value is empty.
Detect a Locked Out User
Set the OTP verification action's error handling to Continue and connect its error output into a condition, with the key set to remainingOTPAttempts, the operator set to Greater Than, and the value set to 0. With the default Automatic handling the user is returned to the previous screen and the condition never runs.
The If branch means the user still has attempts left, so return them to the code entry screen. The Else branch means they are locked out, and you can route them to a dedicated screen, a custom error message, or an account recovery step.
Warn Before Lockout
To warn the user on their final attempt, change the If value from 0 to 1, then add an Else if with the operator set to Equals and the value set to 1. Connect it to a screen that makes the consequence explicit, such as prompting the user to request a new code rather than risk being locked out.
This gives you three branches, evaluated in order: Greater Than 1 for users with attempts to spare, Equals 1 for the final attempt warning, and Else for the lockout. Leaving the If at 0 makes the Else if unreachable, since a value of 1 already satisfies Greater Than 0.
Show the Remaining Count
To show the user where they stand, reference remainingOTPAttempts as a dynamic value in a screen's text component or in a customized error message on the verification action. See Dynamic Values in Flow Errors.