—Rate this article—
 

Raise Fault policy

 Raise Fault policy

About | Samples | Element reference | Error codes | Schema | Related topics

What

Generates a custom message in response to an error condition. Use RaiseFault to define a FaultResponse that is returned to the requesting app when a specific condition arises.

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

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


Element reference

The element reference describes the elements and attributes of the RaiseFault policy.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>Raise Fault 1</DisplayName>
    <FaultResponse>
        <Set>
            <Headers/>
            <Payload contentType="text/plain"> </Payload>
            <StatusCode>500</StatusCode>
            <ReasonPhrase>Server Error</ReasonPhrase>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> attributes

<ResetQuota async="false" continueOnError="false" enabled="true" name="Reset-Quota-1">
Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different from the pool servicing the request/response flow.

Note: This setting is only used for for internal optimization. Contact Apigee Support via the Support Portal for more information.

false Optional
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies. For example, when a quota is exceeded, an error will be raised.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-lanaguage name.

N/A Required

<DisplayName> element

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>RaiseFault 1</DisplayName>
Default: Policy name attribute value.
Presence: Required
Type: String

<FaultResponse> element

(Optional) Defines the response message returned to the requesting client. FaultResponse uses the same settings as the AssignMessage policy type. See Assign Message policy.

<FaultResponse>/<Set>/<Headers> element

Sets or overwrites HTTP headers in the message variable specified with the <AssignTo> element. Note that the empty header <Set><Headers/></Set> does not set any header. This example sets the user-agent header to the message variable specified with the <AssignTo> element.

<Set>     
    <Headers>      
        <Header name="user-agent">{request.header.user-agent}</Header>     
    </Headers> 
</Set>

Default:

N/A

Presence:

Optional

Type:

String

<FaultResponse>/<Set>/<Payload> element

You are allowed to set mixed payload contents. For example, <root><e1>sunday</e1><e2>funday</e2><e3>{var1}</e3></root>.

<Set source='request'>     
    <Payload>true</Payload>      
</Set>

Default:

false

Presence:

Optional

Type:

Boolean

Attributes

<Payload contentType="content_type">
Attribute Description Presence Type
contentType

If contentType is specified, its value is assigned to the contentType header.

Optional String

<FaultResponse>/<Set>/<StatusCode> element

Sets the status code and reason phrase only when AssignTo type is response.

Default:

false

Presence:

Optional

Type:

Boolean

<Set source='request'>     
    <StatusCode>true</StatusCode>      
</Set>

<FaultResponse>/<Set>/<ReasonPhrase> element

Sets the status code and reason phrase only when AssignTo type is response.

Default:

false

Presence:

Optional

Type:

Boolean
<Set source='request'>     
    <ReasonPhrase>true</ReasonPhrase>     
</Set>

<IgnoreUnresolvedVariables> element

(Optional) Ignores any unresolved variable error in the Flow. Valid values: true/false. Default true.

Usage notes

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.

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.

Variable Type Permission Description
fault.name String Read-Only Returns the fault name in the error and if not available, an empty string.
fault.type String Read-Only Returns the fault type in the error and if not available, an empty string.
fault.category String Read-Only Returns the fault category in the error and if not available, an empty string.

Error codes

This policy defines the following error codes. For guidance on handling errors, see Fault handling.

The default format for error codes returned by policies is:

{   "code" : " {ErrorCode} ",   
    "message" : " {Error message} ",   
    "contexts" : [ ] 
}

Schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Related topics

See Fault handling

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)