Exception handling with RaiseFault

The API Platform enables you to configure custom exception handling using a policy of type RaiseFault.

The RaiseFault policy is a variation on the AssignMessage policy type. Like an AssignMessage policy, a RaiseFault policy generates a custom message in response to an error condition. You use RaiseFault to define a FaultResponse that is returned to the requesting app when a specific condition arises.

A FaultResponse can consist of HTTP headers, query parameters, and a message payload. These elements can be dynamically populated using variables, enabling you to craft FaultResponses that are tailored to specific failure conditions. Such tailored FaultResponses can be more useful to app developers and app end users than generic error messages or HTTP response codes.

When executed, the RaiseFault policy transfers the message Flow execution to the default ErrorFlow, which in turn returns the designated FaultResponse to the requesting client app. When the message Flow switches to the default ErrorFlow, no further policy processing occurs. All remaining processing Steps are bypassed, and the FaultResponse is returned directly to the requesting app.

Sample RaiseFault policy

In the most common usage, RaiseFault is used to return a custom FaultResponse to the requesting app. For example to return a 404:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

A more complex example involves returning a custom FaultResponse payload, along with HTTP headers and an HTTP status code. In the following example the FaultResponse is populated with an XML message along with the value of single variable--the HTTP status code received by the API Platform from the backend service.

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
 <FaultResponse>
<RaiseFault>

For a list of all variables that are available for dynamically populating FaultResponse messages, see Variables reference

Configuring a Raise Fault policy

Configure the RaiseFault policy using the following elements.

Policy schema

Polices conform to a policy schema. All policy constructs such as elements and attributes mentioned above are defined in a schema. To download the schema, click here.

Example - RaiseFault policy

<RaiseFault name="abc">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Copy source="sc.response">  <!-- source is optional.. default is message -->
      <Headers />
   </Copy>
   <Remove>
      <Headers>
         <Header name="h1"/>
      </Headers>
   </Remove>
   <Set>
     <Headers>
       <Header name="h1">hello {user}</Header>
       <Header name="h2"/>bye {user}</Header>
       <Header name="h3.2"/>bye {user}</Header>
     </Headers>
     <Payload contentType="text/xml">
       <root>this is my payload {variable.v1}</root>
     </Payload>
     <StatusCode>{response.status.code} OR 500</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

RaiseFault flow variables

Flow variables enable dynamic behavior of policies and Flows at runtime, based on HTTP headers, message content, or Flow context. The following predefined Flow variables are available after a RaiseFault policy executes. For more information about Flow variables, see Variables reference.