What you need to know about policy errors

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

This topic describes the structure of policy errors and the kinds of flow variables that are set when a policy error occurs. This information is essential if you're designing and implementing fault handling for your proxies.

This topic assumes you have a general understanding of how fault handling works in Edge, and that you know what fault rules are. If you need a review, see Handling faults. The information here will also help you navigate and use the Policy error reference.

About the default policy error response

When a policy throws an error, Edge immediately enters the error flow and generates an error message. This system-generated message is a JSON object that includes two bits of information: an errorcode and a faultstring.

For example:

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"foo message is not available for ExtractVariable: ParseJsonResponse"
   }
}

Let's quickly deconstruct this error message:

The errorcode consists of a prefix and an error name, as follows: [prefix].[error_name]. In the above example "steps.extractvariables" is the prefix and SourceMessageNotAvailable is the error name. The prefix tells you what kind of policy generated the error. In the above example, you can tell that an Extract Variables policy generated the error and the error name is SourceMessageNotAvailable.

The faultstring contains a description of the error. The fault string typically includes clues to help you find specific problem that caused the error, such as the name of the policy, the name of an unresolved variable, or whatever contributed to the error. For example, in the above error message, "foo" happens to be the name of an unresolved message variable referenced in the policy and "ParseJsonResponse" is the name of the policy that triggered the error.

Variables specific to policy errors

When a policy error is triggered, certain error-specific flow variables are populated. These variables are extremely useful in fault handling. As explained in the topic Handling faults, it's a common practice to trap the system-generated policy errors and perform a subsequent action such as to create a custom error response. For example, for security reasons, you might want to prevent clients from seeing the actual errors and status codes that Edge returns.

The fault.name variable

When a policy throws an error, it sets the flow variable fault.name to the error_name part of the errorcode (as described in the previous section). It's very common to evaluate this variable to conditionally execute fault rules.

Here's an example fault rule that tests for the value of fault.name:

<faultrule name="VariableOfNonMsgType"<>/faultrule><FaultRule name="Source Message Not Available Fault">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
</FaultRule>

The thing to remember is that when a policy triggers an error, the fault.name variable is always set to the error name.

The [prefix].[policy_name].failed variable

Besides fault.name, another variable that developers commonly check is the [prefix].[policy_name].failed flag, which is set to either true or false when a policy executes. In fault rules, you'll want to check to see when it's true -- that is, to check if an error occurred. Here's how to construct a conditional that checks the [prefix].[policy_name].failed flag. To correctly check this variable, you need to know two things:

• The name of the policy you are checking. This is the value of the policy's name attribute, not the display name. This attribute is always included in the policy definition's XML.
• A prefix that is specific to the type of policy you are checking. (We'll explain how to find the prefix below.)

To illustrate, here's another fault rule example. Notice in the outer condition how the [prefix].[policy_name].failed variable name is formed. In this case the prefix is extractvariables and the policy name is ParseJsonResponse. In this case, the fault rule will only execute if this variable is true. And, here's a tip: because fault rules can contain multiple steps, this pattern is a nice way to organize fault rules into blocks.

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.ParseJsonResponse.failed = true) </Condition>
</FaultRule>

About the error and message variables

The error variable is only available in the error flow of a proxy. You can get useful information from the error variable, such as the error message, status code, reason phrase, and so on. The formatting pattern for the error variable is:

error.[error_component] = [value]

For example:

error.message = "request message is not available for ExtractVariable: ParseJsonResponse"

and

error.status.code = "500"

The message variable is also available in the error flow and can be used for similar purposes as the error variable. The message variable is special because it is contextual. In a request flow, it behaves like a request variable, and in a response flow, it can be used to get/set response values. If you want to know more, see Use cases for message variables.

Refer to Variables reference for information on all of the Edge variables, including error and message.