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: Continue to the next flow step; this allows you to change the behavior of your flow based on the error that occurred.

based on the error that occurred.

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

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.

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.

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.

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.

Here is an additional example of using a dynamic value of the provided user data within a Sign In/Password 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

npm i --save @descope/react-sdk

Import and initialize SDK

import { AuthProvider } from '@descope/react-sdk'
import { Descope, useDescope } from '@descope/react-sdk'
 
const AppRoot = () => {
	return (
		<AuthProvider
			projectId="__ProjectID__"
			// If the Descope project manages the token response in cookies,
            // a custom domain must be configured
            // (e.g., https://auth.app.example.com)
			// and should be set as the baseUrl property.
			// 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.