Handling Flow Errors

Handling Flow Errors

This guide will cover displaying and controlling behavior around flow errors. Within Descope screens, if an external error is provided during an action, you can transform the error to be a more consumable error for your end user. Outside of screens, you can route based on errors.

Customizing Flow Errors in Flow Builder

Within the Descope flow builder, you can customize errors in various places, such as Descope actions and conditionals. Some screen components can also have customized errors; you can review details for these components within the Flow Components Overview. This section will cover handling errors within Descope actions and conditions.

Actions

Below is an example of an action with multiple errors that can be configured and customized. This example shows the Sign In/Password action, which has multiple errors that can modify their behavior.

When customizing an error behavior within a flow action, the options are:

  • Automatic: Descope will automatically redirect the error to the error message component in the last screen viewed by the end user.

    • When Automatic is selected, you can customize the error message that appears when the action returns the error to the previous screen. Custom error messages will override the system error messages.
  • Custom: Control the next flow step by connecting the custom error; this allows you to change the behavior of your flow based on the error that occurred.

  • Ignore: Continue to the next step in the flow (using success output) regardless of the step's outcome.

Descope error handling configuration within a Descope flow action

Below is an example of the Sign In/Password action with two custom error handling configurations selected. Within the flow, you can see that the different errors are handled differently as the flow proceeds. You can use additional actions, screens, or conditions to configure custom actions. An enhanced example of this behavior would be using custom error codes from an HTTP connector in a later condition; you can read about this use case here.

Descope error handling of Descope flow action when connected to other tasks within the flow

Conditions

Below is an example of a Descope flow condition configured with multiple conditions and different error handling configurations. Flow conditions have a toggle for each condition to Treat as an error; when toggled, the condition is marked as an error, and the error behavior can be configured.

When customizing an error behavior within a flow condition, the options are:

  • Automatic: Descope will automatically redirect the error to the error message component in the last screen viewed by the end user.
    • When Automatic is selected, you can customize the error message that appears when the action returns the error to the previous screen. Custom error messages will override the system error messages.
  • Continue: This still allows you to configure the error message and handle the following screen displayed to the user or action ran within the flow.

Descope error handling configuration within a Descope condition within a Descope flow - part 1

Descope error handling configuration within a Descope condition within a Descope flow - part 2

Once you have configured the error handling within your condition, you can configure the next steps for the condition to take within your flow based on the error handling. In this example, a 403 or 404 will return to the Sign In screen and display the configured error, while the else condition will continue and get further information from the user.

Descope error handling configuration example of using a dynamic value of an HTTP connector error

Dynamic Values in Flow Errors

Descope's error handling also allows you to utilize dynamic values within customized errors for actions, conditions, etc. Using this functionality would be helpful when you want to display data back to the user during the returned error.

Here is an example of using a dynamic value of the returned response code from an HTTP connector.

Descope error handling configuration example of using a dynamic value of an HTTP connector error

Descope error displayed to user when using a dynamic value of an HTTP connector error

Here is an additional example of using a dynamic value of the provided user data within a Sign In/Password action.

Example of configuring a Descope action to utilize a dynamic value within the error returned to the user

Example of error displayed to a user when using a dynamic value within an Descope flow action

Customizing Flow Errors via Client SDKs

When you want to override or translate Desope's system or customized flow errors, you will utilize Descope's errorTransformer within the front-end client SDK. This section outlines how to use the errorTransformer within your front-end client.

Client SDK

Install SDK

Terminal
npm i --save @descope/react-sdk

Import and initialize SDK

Parameters:

  • baseUrl: Custom domain that must be configured to manage token response in cookies. This makes sure every request to our service is through your custom domain, preventing accidental domain blockages.
  • baseStaticUrl: Custom domain to override the base URL that is used to fetch static files.
import { AuthProvider } from '@descope/react-sdk'
import { Descope, useDescope } from '@descope/react-sdk'
 
const AppRoot = () => {
	return (
		<AuthProvider
			projectId="__ProjectID__"
			baseUrl = "https://auth.app.example.com"
		>
			<App />
		</AuthProvider>
	);
};

Customizing Flow Errors

Below are examples of how to transform errors during flow execution.

If you want to override your customized flow error that is configured within an action, condition, etc., you will create an item in the map like this: "Error Message configured within flow builder":"Overridden Error Message within front-end client" The localization guide provides a more detailed example of this.

import { Descope } from '@descope/react-sdk'
 
const App = () => {
  return (
    {...}
    <Descope
      flowId="my-flow-id"
      onSuccess={(e) => console.log('Logged in!')}
      onError={(e) => console.log('Could not logged in')}
 
      const errorTransformer = useCallback(
      	(error: { text: string; type: string }) => {
      		const translationMap = {
      			SAMLStartFailed: 'Failed to start SAML flow'
      		};
      		return translationMap[error.type] || error.text;
      	},
      	[]
      );
      errorTransformer={errorTransformer}
    />
  )
}

Localizing Flow Errors

You can also localize flow errors for different languages. For an example of localizing flow errors in multiple languages, see the Localization guide.

Customizable Errors

Below outlines the Descope system error types you can transform when running Descope flows.

CategoryErrors
OTP
  • OTPSignUpOrInEmailFailed
  • OTPSignUpOrInPhoneFailed
  • OTPVerifyCodeEmailFailed
  • OTPVerifyCodePhoneFailed
  • OTPUpdateUserEmailFailed
  • OTPUpdateUserPhoneFailed
  • OTPUnauthorizedRequest
  • OTPSignInEmbeddedFailed
  • OTPSignUpOrInEmbeddedFailed
  • OTPSignUpEmbeddedFailed
  • OTPVerifyEmbeddedFailed
TOTP
  • TOTPSignUpFailed
  • TOTPVerifyCodeFailed
  • TOTPUpdateUserFailed
  • TOTPUnauthorizedRequest
Magic Link
  • MagicLinkSignUpOrInFailed
  • MagicLinkSignUpOrInFailed
  • MagicLinkMisconfiguration
  • MagicLinkUpdateUserEmailFailed
  • MagicLinkUpdateUserPhoneFailed
  • MagicLinkUnauthorizedRequest
  • MagicLinkVerifyFailed
Enchanted Link
  • EnchantedLinkSignUpOrInFailed
  • EnchantedLinkMisconfiguration
  • EnchantedLinkUpdateUserEmailFailed
  • EnchantedLinkUnauthorizedRequest
  • EnchantedLinkVerifyFailed
Embedded Link
  • EmbeddedLinkSignUpOrInFailed
  • EmbeddedLinkSignInFailed
  • EmbeddedLinkSignInFailed
  • ActionErrorEmbeddedLinkUpdateUser
  • ActionErrorEmbeddedLinkUnauthorizedRequest
Social (OAuth)
  • OAuthStartFailed
  • OAuthMisconfiguration
  • OAuthExchangeCodeFailed
Biometrics (WebAuthn)
  • WebauthnFailed
  • WebauthnSignUpStartFailed
  • WebauthnSignUpFinishFailed
  • WebauthnSignInStartFailed
  • WebauthnSignInFinishFailed
  • WebauthnSignUpOrInStartFailed
  • WebauthnSignUpOrInFinishFailed
  • WebauthnUpdateUserStartFailed
  • WebauthnUnauthorizedRequest
  • WebauthnUpdateUserFinishFailed
SAML Login
  • SAMLStartFailed
  • SAMLMisconfiguration
  • SAMLExchangeCodeFailed
Passwords
  • PasswordSignUpFailed
  • PasswordSignInFailed
  • PasswordExpired
  • PasswordSendResetFailed
  • PasswordUpdateFailed
  • PasswordReplaceFailed
  • PasswordUpdateFailed
Tenants & SSO Config
  • TenantCreation
  • SetSAMLConfigFailed
  • GetSAMLConfigFailed
  • SAMLConfigSelectTenant
  • ConfigProvideTenant
  • GetTenantConfigFailed
  • SetTenantConfigFailed
User Invites
  • InviteUsersSelectTenant
  • InviteUsersPermissions
  • InviteUsers
Roles
  • GetDefaultRoles
  • AssignRoles
  • ActionErrorAddRolesFailed
  • ActionErrorAddRolesFailedDoNotExists
Connectors
  • ConnectorFailed
  • EmailConnectorFailed
  • SMSConnectorFailed
User Impersonation
  • ImpersonationConsent
  • ActionErrorImpersonateFailed
  • ActionErrorImpersonateNoPermission
  • ActionErrorImpersonateConsent
  • ActionErrorMissingImpersonatingUser
General
  • InvalidJWT
  • LoggedInFailed
  • ActionErrorLoadUserFromJWTFailed
  • ActionErrorLoadUserJwtVerify
  • ActionErrorLoadUserNoUser
  • ActionErrorParseCustomClaims
  • ActionErrorUpdateJWT
  • UpdateUserPropertiesFailed
Was this helpful?

On this page