Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Raise Fault policy

What

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

For general information on handling faults, see Handling faults

Where

This policy can be attached in the following locations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    レスポンス
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

In the most common usage, Raise Fault is used to return a custom fault response 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 fault response payload, along with HTTP headers and an HTTP status code. In the following example the fault response is populated with an XML message containing the HTTP status code received by Edge from the backend service, and a header containing the type of fault that occurred:

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

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

Learn by doing!
This Learn Edge example shows you how to check the HTTP code in a Service Callout response and throw a custom exception based on the value of the code. The example returns a custom error message when the target service returns a 404 status. Just clone the repository and follow the instructions in that topic. The example illustrates a common pattern for handling service callout errors. .


About the Raise Fault policy

Apigee Edge enables you to perform custom exception handling using a policy of type Raise Fault. The Raise Fault policy, which is a variation of the Assign Message policy, lets you generate a custom fault response in response to an error condition. 

Use the Raise Fault policy to define a fault response that is returned to the requesting app when a specific error condition arises. The fault response can consist of HTTP headers, query parameters, and a message payload. A custom fault response can be more useful to app developers and app end users than generic error messages or HTTP response codes.

When executed, the Raise Fault policy transfers control from the current flow to the Error flow, which then returns the designated fault response to the requesting client app. When the message Flow switches to the Error flow, no further policy processing occurs. All remaining processing Steps are bypassed, and the fault response is returned directly to the requesting app.

There are two main places where you use the Raise Fault policy:
  • In a ProxyEndpoint/TargetEndpoint flow to trigger a fault in response to a condition or set of conditions. That fault can trigger a specific fault rule or, if there are no fault rules defined, it terminates processing of the proxy.
  • In a fault rule if you want to detect an error during processing of a fault. For example, your fault handler itself could cause an error that you want to signal by using Raise Fault.

See Handling faults for more.

Element reference

The element reference describes the elements and attributes of the Raise Fault 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>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> attributes

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

The following attributes are common to all policy parent elements.

Attribute 説明 デフォルト Presence
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-language name.

該当なし Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

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
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default:

該当なし

If you omit this element, the value of the policy's name attribute is used.

Presence: Optional
Type: 文字列

 

<IgnoreUnresolvedVariables> element

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

<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><Copy> element

Copies information from the message specified by the source attribute to the error message.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
        <ReasonPhrase/>
    </Copy>

Default:

該当なし

Presence:

Optional

Type:

文字列

属性

<Copy source="response">
Attribute 説明 Presence
source

Specifies the source object of the copy.

  • If source is not specified, it is treated as a simple message. For example, if the policy is in the request flow, then the source defaults to the request object. If the policy is in the response flow, it defaults to the response object. If you omit source, you can use an absolute reference to a flow variable as the source of the copy. For example, specify the value as {request.header.user-agent}.
  • If the source variable cannot be resolved, or resolves to a non-message type, <Copy> fails to respond.
Optional 文字列

<FaultResponse><Copy>/<Headers> element

Copies the specified HTTP header from the source to the error message. To copy all headers, specify <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>      
        <Header name="headerName"/>     
    </Headers> 
</Copy>

If there are multiple headers with the same name, use the following syntax:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

This example copies "h1", "h2", and the second value of "h3". If "h3" has only one value, then it is not copied.

Default:

該当なし

Presence:

Optional

Type:

文字列

<FaultResponse><Copy>/<StatusCode> element

The HTTP status code to copy from the object specified by the source attribute to the error message.

<Copy source='response'>
    <StatusCode>404</StatusCode>      
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<FaultResponse><Copy>/<ReasonPhrase> element

The reason description to copy from the object specified by the source attribute to the error message.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

Default:

false

Presence:

Optional

Type:

Boolean

<FaultResponse><Remove>/<Headers> element

Removes specified HTTP headers from the error message. To remove all the headers, specify <Remove><Headers/></Remove>. This example removes the user-agent header from the message.

<Remove>     
    <Headers>      
        <Header name="user-agent"/>     
    </Headers> 
</Remove>

If there are multiple headers with the same name, use the following syntax:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

This example removes "h1", "h2", and the second value of "h3". If "h3" has only one value, then it is not removed.

Default:

該当なし

Presence:

Optional

Type:

文字列

<FaultResponse><Add>/<Headers> element

Adds HTTP headers to the error message. Note that the empty header <Add><Headers/></Add> does not add any header. This example copies the value of the request.user.agent flow variable into the header.

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

Default:

該当なし

Presence:

Optional

Type:

文字列

<FaultResponse><Set> element

Sets information in the error message.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
        <ReasonPhrase/>
    </Set>

Default:

該当なし

Presence:

Optional

Type:

該当なし

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

Sets or overwrites HTTP headers in the error message. 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:

該当なし

Presence:

Optional

Type:

文字列

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

Sets the payload of the error message.

<Set>     
    <Payload contentType="text/plain">test1234</Payload>      
</Set>

Set a JSON payload:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

In a JSON payload, you can insert variables using the variablePrefix and variableSuffix attributes with delimiter characters as shown in the following example.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

or, as of cloud release 16.08.17, you can also curly braces to insert variables:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Set a mixed payload in XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>          

Default:

 

Presence:

Optional

Type:

文字列

属性

<Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
Attribute 説明 Presence
contentType

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

Optional 文字列
variablePrefix Optionally specifies the leading delimiter on a flow variable because JSON payloads cannot use the default "{" character. Optional Char
variableSuffix Optionally specifies the trailing delimiter on a flow variable because JSON payloads cannot use the default "}" character. Optional Char

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

Sets the status code of the response.

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

Default:

false

Presence:

Optional

Type:

Boolean

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

Sets the reason phrase of the response.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Set>

Default:

false

Presence:

Optional

Type:

Boolean

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 Raise Fault policy executes. For more information about Flow variables, see Variables reference.

変数 Permission 説明
fault.name 文字列 読み取り専用 Returns the fault name in the error and if not available, an empty string.
fault.type 文字列 読み取り専用 Returns the fault type in the error and if not available, an empty string.
fault.category 文字列 読み取り専用 Returns the fault category in the error and if not available, an empty string.

Error reference

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules to handle errors. To learn more, see What you need to know about policy errors and Handling faults.

Error code prefix

steps.raisefault (What's this?)

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
RaiseFault 500 See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where
[prefix].[policy_name].failed The [prefix] is raisefault.
The [policy_name] is the name of the policy that threw the error.
raisefault.RF-ThrowError.failed = true
fault.[error_name] [error_name] = The specific error name to check for as listed in the table above. fault.name = "RaiseFault"

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Example fault rule

<FaultRule name="RaiseFault">
    <Step>
        <Name>RF-ThrowError</Name>
        <Condition>(fault.name Matches "RaiseFault") </Condition>
    </Step>
</FaultRule>

スキーマ

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

関連トピック

See Handling faults

 

Help or comments?