How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I customize exceptions thrown for custom endpoints in IDM (All versions)?

Last updated Jan 12, 2023

The purpose of this article is to provide information on customizing exceptions thrown for custom endpoints in IDM. This allows you to output a custom message for standard HTTP error codes.

Customizing exceptions

You can add exceptions to endpoints as detailed in the documentation: Script Exceptions.

If you want to customize the error response further, you can add information to the detail property (JavaScript®) or setDetail (Groovy); the code and reason properties are reserved for the standard HTTP error codes and messages.


You want to include the following additional details for a 404: Not Found error code:

  • custom error code
  • custom message
  • description
  • severity rating

Add the following code to your script depending on your script type:

  • JavaScript: throw { code : 404, message : "Error", detail: { code: "ERROR1", description : "Custom error description", severity : "Fatal" } }
  • Groovy: import org.forgerock.json.resource.ResourceException import org.forgerock.json.JsonValue throw new ResourceException(404, "Error").setDetail(new JsonValue([ "code": "ERROR1", "description": "Custom error description", "severity": "Fatal" ]))

These code changes will output the following response when a 404 error is encountered:

{ "code": 404, "reason": "Not Found", "message": "Error", "detail": { "code": "ERROR1", "severity": "Fatal", "description": "Custom error description" } }

See Also

How do I write to a file using JavaScript on a custom endpoint in IDM (All versions)?

How do I customize authorization rules for http requests in IDM 6.x?

How do I add logging to JavaScript files in IDM (All versions)?

FAQ: Scripts in IDM

Scripts in IDM

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.