--- title: Set Failure Details node description: The Set Failure Details node adds details to the JSON response when a journey ends in failure. You can configure the node properties to: component: auth-node-ref version: latest page_id: auth-node-ref::set-failure-details canonical_url: https://docs.pingidentity.com/auth-node-ref/latest/set-failure-details.html keywords: ["Nodes & Trees", "Journeys", "Authentication"] superseded_by: https://docs.pingidentity.com/auth-node-ref/latest/set-failure-details.html section_ids: examples: Examples example_1_add_a_failure_message_and_details_on_account_lockout: "Example 1: Add a failure message and details on account lockout" example_2_set_custom_response_headers: "Example 2: Set custom response headers" availability: Availability inputs: Inputs dependencies: Dependencies configuration: Configuration outputs: Outputs callbacks: Callbacks outcomes: Outcomes errors: Errors --- # Set Failure Details node The Set Failure Details node adds details to the JSON response when a journey ends in failure. You can configure the node properties to: * Return a failure message. * Include extra information in the response body in the form of static `key:value` fields. * Set custom response headers. You can't modify the protected HTTP headers, nor can you modify the session cookie or load balancer cookie using the `Set-Cookie` header. > **Collapse: 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` ## Examples ### Example 1: Add a failure message and details on account lockout This example uses the Set Failure Details node and assumes the following configuration: * Failure Message * Key: `en-gb` * Value: `Your account is locked` * Failure Details * Key: `Reason` * Value: `Exceeded max retries` ![Journey with a Set Failure Details node](_images/set-failure-success-details-journey.png) * The [Page node](page.html) containing the [Platform Username node](platform-username.html) and [Platform Password node](platform-password.html) prompts for credentials. * The [Data Store Decision node](data-store-decision.html) validates the username-password credentials. * If authentication is successful: * The [Increment Login Count node](increment-login-count.html) updates the number of successful authentications in the user profile. * The [Set Success Details node](set-success-details.html) adds any configured details to the JSON response. * If authentication fails: * The [Retry Limit Decision node](retry-limit-decision.html) checks the number of failed authentications against the configured limit. If the retry limit is reached, the journey continues on the `Reject` outcome path. * The [Account Lockout node](account-lockout.html) locks the account. * The Set Failure Details node displays the configured message to the user and adds both the message and the details to the JSON response. For example: ```json { "code":401, "reason":"Unauthorized", "message":"Your account is locked", "detail":{ "Reason":"Exceeded max retries" } } ``` ### Example 2: Set custom response headers This example uses the Set Failure Details node to set a `Custom-Fail` response header when the journey ends in failure after locking the user's account. This header could be read by a custom UI to trigger a specific action when the user's account is locked. ![Journey with a Set Failure Details node to set custom response headers](_images/set-failure-header-journey.png) * The [Page node](page.html) containing the [Platform Username node](platform-username.html) and [Platform Password node](platform-password.html) prompts for credentials. * The [Data Store Decision node](data-store-decision.html) validates the username-password credentials. * If authentication is successful, the [Increment Login Count node](increment-login-count.html) updates the number of successful authentications in the user profile. * If authentication fails: * The [Account Lockout node](account-lockout.html) locks the account. * The Set Failure Details node sets the response header. This example uses the following configuration: * Response Headers Key: `Custom-Fail` Value: `account-locked` Follow these steps to try the example: 1. Create the example journey using the journey editor. 2. Authenticate a test user with the journey using incorrect credentials. Make sure you include the `--show-headers` option (or `--include` in older `curl` versions) to return the response headers: ```bash $ curl --show-headers \ --request POST \ --header 'X-OpenAM-Username: bjensen' \ --header 'X-OpenAM-Password: wrong-password' \ --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-Fail: account-locked ... { "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 | ## Inputs None. This node doesn't read shared state data. ## Dependencies This node has no dependencies. ## Configuration | Property | Usage | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Failure Message | The message to add to the JSON response when authentication fails:Add a custom, localized message per locale:1) Click [icon: plus, set=fa]. 2) In the Key field, enter the locale. For example, `en-gb`.[1](#locale-footnote) 3) In the Value field, enter the message. For example, `Your account has been locked`. 4) Click Done. 5) Repeat to add more messages and save your changes when you're done. | | Failure Details | The details to add to the JSON response on journey failure:1) Click [icon: plus, set=fa]. 2) In the Key field, enter a name to identify the details. For example, `Reason`. 3) In the Value field, enter the details to return. For example, `Exceeded max retries`. 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" } 4) Click Done. 5) Click [icon: plus, set=fa]Add to repeat and add more details. 6) Save your changes. | | Response Headers | The response headers to set:- To add a response header: 1. Click [icon: plus, set=fa]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 ([icon: pencil-alt, set=fa]). 2. Update the Key and Value as when adding headers. - To remove a response header, click the Delete icon ([icon: trash, set=fa]).When finished, click Save to keep your settings. | (1) Specify a [locale that Java supports](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Locale.html), 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 failure, this node adds the configured details to the JSON response. ## Errors This node doesn't log any error or warning messages of its own.