This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
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 Apigee, 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, Apigee 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":"mymessage 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 ExtractVariables 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 the 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, mymessage 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 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 Apigee 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.
<faultrulename="VariableOfNonMsgType"></faultrule><FaultRulename="Extract Variable Faults"> <Step> <Name>AM-CustomErrorMessage</Name> <Condition>(fault.nameMatches"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, and so on. The formatting pattern for the error variable is the following:
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.
Refer to Flow variables reference for information on all of the Apigee variables, including error and message.
