Policy Fault Handling

Error handling shouldn't be this hard. Check out this post for a really clean pattern for error handling: https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

I have used it on four or five projects, and it really makes it easier to define your error types, content and presentation.

@Edward Glad I'm not the only one struggling to come up with a clean and manageable solution to this, I would like to differentiate among multiple JavaScript, ServiceCallout, and conditional RaiseFaults policies.

I discovered a pattern that works by checking for the explicit "policy-name" that failed. I haven't tested it for all policy types nor do I have a comprehensive list of the "policy-type" values. Perhaps that should be added to the Error Code Reference page.

User an "outer" condition to catch the "fault.name" and then use an "inner" condition to differentiate by checking for the "policy-name".faile = true.

{policy-type}.{policy-name}.failed = true

For RaiseFault differentiation, you can check

raisefault.{policy-name}.failed

Then in your FaultRules section use this outer condition and inner conditions:

<FaultRule name="raise-faults">
    <Condition>(fault.name = "RaiseFault")</Condition>
    <Step>
        <Condition>(raisefault.RF-missing-required-params.failed = true)</Condition>
        <Name>AM-missing-required-params</Name>
    </Step>
    <Step>
        <Condition>(raisefault.RF-invalid-hmac.failed = true)</Condition>
        <Name>AM-invalid-hmac</Name>
    </Step>
    <Step>
        <Condition>(raisefault.RF-path-suffix-not-found.failed = true)</Condition>
        <Name>AM-resource-not-found</Name>
    </Step>
</FaultRule>

For JavaScript differentiation, you can check

javascript.{policy-name}.failed

Then in your FaultRules section use this outer condition and inner conditions:

<FaultRule name="script-error">
    <Condition>(fault.name = "ScriptExecutionFailed")</Condition>
    <Step>
        <Condition>(javascript.JS-verify-hmac.failed = true)</Condition>
        <Name>AM-Set-Script-Execution-Error-Variables</Name>
    </Step>
    <Step>
        <Condition>(javascript.JS-log.failed = true)</Condition>
        <Name>AM-Set-Script-Execution-Error-Variables</Name>
    </Step>
</FaultRule>

For ServiceCallout differentiation, you can use:

servicecallout.{policy-name}.failed

Then in your FaultRules section use this outer condition and inner conditions:

<FaultRule name="service-callout-error">
    <Condition>(fault.name = "ExecutionFailed")</Condition>
    <Step>
        <Condition>(servicecallout.SC-Get-OAuth-Token.failed = true)</Condition>
        <Name>AM-Set-SC-Execution-Get-OAuth-Variables</Name>
     </Step>
     <Step>
        <Condition>(servicecallout.SC-Get-Refresh-Token.failed = true)</Condition>
        <Name>AM-Set-SC-Execution-Get-Refresh-Variables</Name>
     </Step>
</FaultRule>

The problem with this approach is how to catch remaining "policy-type" errors that don't match the inner conditions. A Step with no condition will always execute and checking the opposite conditions is combersome. See below for a more managable approach.

The problem with the above approach, is that once the outer condition matches, no other fault rules "outer" conditions will be matched and it is cumbersome to determine the unmatched condition.

So, rather than use and outer condition to match the fault type and an inner condition to match the specific, using a FaultRule with only outer conditions provides easier management of un-matched conditions, as would be the case if you forgot to add a specific condition.

Consider the following approach:

    <!-- RAISE FAULTS SECTION -->
    <FaultRule name="Raise-fault-not-specific">
	<!-- DEFAULT or UNMATCHED RASIE FAULT -->
        <Condition>(fault.name = "RaiseFault")</Condition>
        <Step>
            <Name>AM-default-raise-fault</Name>
        </Step>
    </FaultRule>

    <FaultRule name="Raise-fault-required-params">
        <Condition>(fault.name = "RaiseFault") and (raisefault.RF-missing-required-params.failed = true)</Condition>
        <Step>
            <Name>AM-missing-required-params</Name>
        </Step>
    </FaultRule>

    <FaultRule name="Raise-fault-invalid-hmac">
        <Condition>(fault.name = "RaiseFault") and (raisefault.RF-invalid-hmac.failed = true)</Condition>
        <Step>
            <Name>AM-invalid-hmac</Name>
        </Step>
    </FaultRule>

    <FaultRule name="Raise-fault-suffix-not-found">
        <Condition>(fault.name = "RaiseFault") and (raisefault.RF-path-suffix-not-found.failed = true)</Condition>
        <Step>
            <Name>AM-resource-not-found</Name>
        </Step>
    </FaultRule>

This allows you to differentiate among all RaiseFaults and to catch any unmatched specific RaiseFault conditions using the "AM-default-raise-fault" at the top, which also demonstrates that FaultRule conditions are evaluated from bottom-to-top."

The use of Assign Message in the steps is to set variables for subsequent use in the DefaultFaultRule as described here: https://community.apigee.com/content/kbentry/23724/an-error-handling-pattern-for-apigee-proxies.html