HTTP and Response Code Error Handling
  • 09 Jul 2024
  • 2 Minutes to read
  • Dark
    Light

HTTP and Response Code Error Handling

  • Dark
    Light

Article summary

Overview 

Decisions Flows, Rules, and Reports can be called as REST APIs using most typical REST Method such as Get, Post, and Put.  Given that the Workflows in Decisions are highly configurable by the Designer, it is not always possible to return standard HTTP codes. The following document describes how Decisions handles certain types of Error conditions and how the Designer can configure the Flows to throw specific codes and Error Messages when required.

Additional Information 
For additional information regarding Exception Handling Exception Handling Best Practices.

Expected API Exception Return 

Unless otherwise specified in the Flow designs covered below, Decisions returns two things when an Exception occurs while calling a Flow as an API.

  • HTTP Status Code
  • A Plain Text Error Message to the Calling System

The screenshot below displays a typical Error Message in Postman


Standard HTTP Code Patterns: Succesful Calls

200 Success

Successful calls into the Workflow Engine will return a 200 Response. This means that the Flow Diagram was able to make its way from the Start step to the End step without encountering an uncaught Exception. Steps in Flows can have Outcomes for Errors/No Data Return that can be Error Conditions. If the Flow is built to incorrectly handle these scenarios Flow design can inadvertently appear to succeed to the Calling System.


Standard HTTP Code Patterns: Failed Calls 

403 Forbidden 

Requests missing Authentication or having invalid Authentication will return HTTP Error Code 403.

500 Internal Server Errors 

Almost all other Exception events occurring during the calling or execution of a Flow will return a 500 Internal Server Error to the Calling System. Below are a few examples:

  • Step hits an uncaught Exception that causes the Flow to Fail to continue to its End step.
  • A malformed Request Body is sent; this would typically be a 400 Error in other Web Applications.
Note on False Success Response 
Please note that certain ExceptionHandling patterns can cause Calling Systems to receive a 200 Success Response even if an Error has occurred. This is most likely when Assigned Forms are used to Catch Exceptions for Administrators to follow up.

Examples of Malformed Request Responses 

  • Input Property Misnamed:  “Input parameter [Property Name] is missing.”
  • Input Property Missing: “Input parameter [Property Name] is missing.”
  • Invalid DataType:  “Input string was not in a correct format.”
  • Malformed JSON:  “There is an error in XML document (1, 1).” 

Throwing Explicit Errors to Calling Systems 

The Flow Designer allows users to throw specific Error Messages and Codes to Calling Systems at any time using the Throw API Exception step. This allows a Designer to handle any Runtime Event as an Error alerting the Calling System of something adverse occurring.

Additional Information on Throw API Exception 
Note that the Throw API Exception step has no associated OutcomePath

Upon reaching this step, the Flow will direct to the End step of the Flow. 


Serializing Error Messages 

Because the Error Message is just a Plain String [Text] input users may leverage the ability to Serialize Data into JSON/XML as means of returning Data in a configurable format.
To do so:

  1. From the Flow Designer, add a Catch Exception step from Toolbox > FLOW MANAGEMENT > ERROR HANDLING to the Flow structure. 
  2. From the Toolbox > DATA > JSON category, attach a JSON Serialize step to the On Exception path of the Catch Exception step.
  3. From the Properties tab of the JSON Serialize step, select String [Text] from Type, then Select From Flow map ExceptionMessage to the Object to Serialize Input. 
  4. From the same ERROR HANDLING category of the Toolbox tab that the Catch Exception step came from, attach a Throw Exception step to the Done and Error paths of the JSON Serialize step. 
  5. From the Properties of the Throw Exception step, map JsonSerialize1_Output to the Message Input. 
Note on Flow Design 
This Flow design allows users to control the Error Message Response with the same level of detail that they are able to control the data returned from a Successful call.

For further information on Integrations, visit the Decisions Forum.

Was this article helpful?