Set Error Details node

The Set Error Details node adds details to the JSON response when a journey ends in an error. You can configure the node properties to:

Return an error message.
Include extra information in the response body in the form of static key:value fields.
Set custom response headers. RAPID only
You can’t modify the protected HTTP headers, nor can you modify the session cookie or load balancer cookie using the Set-Cookie header.
Protected HTTP headers
X-Frame-Options

X-Content-Type-Options

Cache-Control

Content-API-Version

Expires

Pragma

Content-Type

Content-Length

Date

Keep-Alive

Connection

Transfer-Encoding

Server

Trailer

Upgrade

Place the Set Error Details node before the node that errors in the journey.

Examples

Example 1: Handle identity assertion errors

This example uses the Set Error Details node to handle errors from the Identity Assertion node when the journey ends in an error.

The Set Error Details node adds details to the JSON response when the journey ends in an error. This example uses the following configuration:
Error Message

Key: en-gb

Value: Identity assertion failure

Error Details

Key: errorUrl

Value: https://example.com/error
The Identity Assertion node is configured as described in the documentation.

If an error is encountered, the Set Error Details node displays the configured message to the user and adds both the message and the details to the JSON response.

For example:
```
{
    "code": 401,
    "reason": "Unauthorized",
    "message": "Identity assertion failure",
    "detail": {
      "errorUrl": "https://example.com/error"
    }
}
```

Example 2: Set custom response headers

RAPID only

This example uses the Set Error Details node to set a Custom-Error response header when the journey ends in an error. This header could be read by a custom UI or a legacy application to trigger a specific action when an error is encountered.

To simulate an error for demonstration purposes, this simple login journey includes a script that errors.

Journey with a Set Error Details node setting a response header

The Page node containing the Platform Username node and Platform Password node prompts for credentials.
The Data Store Decision node validates the username-password credentials.
The Set Error Details node sets the response header when the journey ends in an error. This example uses the following configuration:

Response Headers

Key: Custom-Error

Value: error-encountered
The Scripted Decision node calls the following script, which expects an outcome of next but the node is configured with an outcome of true:
```
action.goTo("next");
```
When the script runs, the journeys ends in an error because the next outcome doesn’t exist. The Set Error Details node sets the configured response header.

Follow these steps to try the example:

Create the example journey using the journey editor.

Authenticate a test user with the journey. Make sure you include the --show-headers option (or --include in older curl versions) to return the response headers:

$ curl --show-headers \
--request POST \
--header 'X-OpenAM-Username: bjensen' \
--header 'X-OpenAM-Password: Ch4ng3it!' \
--header "Accept-API-Version: resource=2.1, protocol=1.0" \
"https://tenant-env-fqdn/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=myJourney"

HTTP/1.1 401
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
...
Custom-Error: error-encountered
...

{
    "code":401,
    "reason":"Unauthorized",
    "message":"Login failure"
}

Availability

Product	Available?
PingOne Advanced Identity Cloud	Yes
PingAM (self-managed)	Yes
Ping Identity Platform (self-managed)	Yes

Product

Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

Inputs

None. This node doesn’t read shared state data.

Dependencies

None.

Configuration

Property Usage

Error Message

The message to add to the JSON response when a journey ends in an error.

Add a custom, localized message per locale:

Click .
In the Key field, enter the locale. For example, en-gb.¹
In the Value field, enter the message. For example, Invalid outcome from script.
Click Done.
Repeat to add more messages and save your changes when you’re done.

Error Details

The details to add to the JSON response when a journey ends in an error:

Click .
In the Key field, enter a name to identify the details. For example, redirect_url.

In the Value field, enter the details to return. For example, https://example.com.

The value can be a simple text string, a boolean value, or a JSON formatted value. The value is formatted appropriately when output in the JSON response.

For example:

Key Value Output

example

this is a test value

"example": "this is a test value"

boolean

true

"boolean": true

field

{ "nested": "nested value" }

"field": {
   "nested": "nested value"
}

Click Done.
Click Add to repeat and add more details.
Save your changes.

Response Headers RAPID only

The response headers to set:

To add a response header:
1. Click Add in the Response Headers modal.
2. Enter the HTTP header name to display in the Key field and the corresponding value to display in the Value field.
3. Click Done.
To edit a response header:
1. Click the Pencil icon ().
2. Update the Key and Value as when adding headers.
To remove a response header, click the Delete icon ().

When finished, click Save to keep your settings.

⁽¹⁾ Specify a locale that Java supports, such as en-gb. Otherwise, the node throws a configuration exception with an Invalid locale provided message.

Outputs

This node doesn’t change the shared state.

Callbacks

This node doesn’t send any callbacks.

Outcomes

Single outcome path: when the journey ends in an error, this node adds the configured details to the JSON response.

Errors

This node doesn’t log any error or warning messages of its own.

Authentication nodes