[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-08-21 (世界標準時間)。"],[[["\u003cp\u003eThe RaiseFault policy allows API developers to initiate error flows and set error variables, including \u003ccode\u003efault.name\u003c/code\u003e, \u003ccode\u003efault.type\u003c/code\u003e, and \u003ccode\u003efault.category\u003c/code\u003e, which are visible in analytics and logs for debugging.\u003c/p\u003e\n"],["\u003cp\u003eUsing the RaiseFault policy within FaultRules after another policy has already thrown an error overwrites the original error information, masking the true cause of the failure in analytics and logs.\u003c/p\u003e\n"],["\u003cp\u003eEmploying the RaiseFault policy in a FaultRule under all conditions similarly overwrites crucial fault variables, making it hard to pinpoint the actual failing policy without a detailed trace or reproducing the issue.\u003c/p\u003e\n"],["\u003cp\u003eUsing the RaiseFault policy outside of the error flow to return HTTP 2xx responses can lead to misleading analytics data because it will contain the RaiseFault policy's name.\u003c/p\u003e\n"],["\u003cp\u003eFor customizing error response messages when an Apigee policy raises a fault, it's best practice to use AssignMessage or JavaScript policies rather than RaiseFault, reserving RaiseFault for non-error flows to treat specific conditions as errors.\u003c/p\u003e\n"]]],[],null,["# Antipattern: Use the RaiseFault Policy under inappropriate conditions\n\n*You're viewing **Apigee** and **Apigee hybrid** documentation.\nView [Apigee Edge](https://docs.apigee.com/api-platform/antipatterns/raise-fault-conditions) documentation.*\n\n\nThe [RaiseFault policy](/apigee/docs/api-platform/reference/policies/raise-fault-policy) lets API developers initiate an error flow, set error variables\nin a response body message, and set appropriate response status codes. You can also use the RaiseFault\npolicy to set flow variables pertaining to the fault, such as, `fault.name`, `fault.type`,\nand `fault.category`. Because these variables are visible in analytics data and Router access logs\nused for debugging, it's important to identify the fault accurately.\n\n\nYou can use the RaiseFault policy to treat specific conditions as errors, even if an actual error has\nnot occurred in another policy or in the backend server of the API proxy. For example, if you want\nthe proxy to send a custom error message to the client app whenever the backend response\nbody contains the string `unavailable`, then you could invoke the RaiseFault policy as\nshown in the code snippet below: \n\n```world-of-warcraft-toc\n\u003c!-- /antipatterns/examples/raise-fault-conditions-1.xml --\u003e\n\u003cTargetEndpoint name=\"default\"\u003e\n...\n \u003cResponse\u003e\n \u003cStep\u003e\n \u003cName\u003eRF-Service-Unavailable\u003c/Name\u003e\n \u003cCondition\u003e(message.content Like \"*unavailable*\")\u003c/Condition\u003e\n \u003c/Step\u003e\n \u003c/Response\u003e\n...\n```\n\n\nThe RaiseFault policy's name is visible as the `fault.name` in [API Monitoring](/apigee/docs/api-monitoring) and as `x_apigee_fault_policy` in the Analytics and Router access logs.\nThis helps to diagnose the cause of the error easily.\n\nAntipattern\n-----------\n\n### Using the RaiseFault policy within FaultRules after another policy has already thrown an error\n\n\nConsider the example below, where an OAuthV2 policy in the API Proxy flow has failed with an `InvalidAccessToken`\nerror. Upon failure, Apigee will set the `fault.name` as `InvalidAccessToken`, enter into\nthe error flow, and execute any defined FaultRules. In the FaultRule, there is a RaiseFault policy named\n`RaiseFault` that sends a customized error response whenever an `InvalidAccessToken`\nerror occurs. However, the use of RaiseFault policy in a FaultRule means that the `fault.name`\nvariable is overwritten and masks the true cause of the failure. \n\n```world-of-warcraft-toc\n\u003c!-- /antipatterns/examples/raise-fault-conditions-2.xml --\u003e\n\u003cFaultRules\u003e\n \u003cFaultRule name=\"generic_raisefault\"\u003e\n \u003cStep\u003e\n \u003cName\u003eRaiseFault\u003c/Name\u003e\n \u003cCondition\u003e(fault.name equals \"invalid_access_token\") or (fault.name equals \"InvalidAccessToken\")\u003c/Condition\u003e\n \u003c/Step\u003e\n \u003c/FaultRule\u003e\n\u003c/FaultRules\u003e\n```\n\n### Using RaiseFault policy in a FaultRule under all conditions\n\n\nIn the example below, a RaiseFault policy named `RaiseFault` executes if the `fault.name`\nis not `RaiseFault`: \n\n```world-of-warcraft-toc\n\u003c!-- /antipatterns/examples/raise-fault-conditions-3.xml --\u003e\n\u003cFaultRules\u003e\n \u003cFaultRule name=\"fault_rule\"\u003e\n ....\n \u003cStep\u003e\n \u003cName\u003eRaiseFault\u003c/Name\u003e\n \u003cCondition\u003e!(fault.name equals \"RaiseFault\")\u003c/Condition\u003e\n \u003c/Step\u003e\n \u003c/FaultRule\u003e\n\u003c/FaultRules\u003e\n```\n\n\nAs in the first scenario, the key fault variables `fault.name`, `fault.code`,\nand `fault.policy` are overwritten with the RaiseFault policy's name. This behavior makes\nit almost impossible to determine which policy actually caused the failure without accessing a trace\nfile showing the failure or reproducing the issue.\n\n### Using RaiseFault policy to return a HTTP 2xx response outside of the error flow.\n\n\nIn the example below, a RaiseFault policy named `HandleOptionsRequest` executes when\nthe request verb is `OPTIONS`: \n\n```world-of-warcraft-toc\n\u003c!-- /antipatterns/examples/raise-fault-conditions-4.xml --\u003e\n\u003cPreFlow name=\"PreFlow\"\u003e\n \u003cRequest\u003e\n ...\n \u003cStep\u003e\n \u003cName\u003eHandleOptionsRequest\u003c/Name\u003e\n \u003cCondition\u003e(request.verb Equals \"OPTIONS\")\u003c/Condition\u003e\n \u003c/Step\u003e\n ...\n\u003c/PreFlow\u003e\n```\n\n\nThe intent is to return the response to the API client immediately without processing other policies.\nHowever, this will lead to misleading analytics data because the fault variables will contain the\nRaiseFault policy's name, making the proxy more difficult to debug. The correct way to implement\nthe desired behavior is to use Flows with special conditions, as described in\n[Adding CORS support](/apigee/docs/api-platform/develop/adding-cors-support-api-proxy).\n\nImpact\n------\n\n\nUse of the RaiseFault policy as described above results in overwriting key fault variables with the\nRaiseFault policy's name instead of the failing policy's name. In Analytics and NGINX Access logs,\nthe` x_apigee_fault_code` and `x_apigee_fault_policy`variables\nare overwritten. In [API Monitoring](https://apigee.com/apimonitoring), the `Fault Code`\nand `Fault Policy `are overwritten. This behavior makes it difficult to troubleshoot and\ndetermine which policy is the true cause of the failure.\n\n\nIn the screenshot below from [API Monitoring](https://apigee.com/apimonitoring),\nyou can see that the Fault Code and Fault policy were overwritten to generic `RaiseFault`\nvalues, making it impossible to determine the root cause of the failure from the logs:\n\nBest Practice\n-------------\n\n\nWhen an Apigee policy raises a fault and you want to customize the error response message,\nuse the AssignMessage or JavaScript policies instead of the RaiseFault policy.\n\n\nThe RaiseFault policy should be used in a non-error flow. That is, only use RaiseFault to treat a specific\ncondition as an error, even if an actual error has not occurred in a policy or in the backend server\nof the API Proxy. For example, you could use the RaiseFault policy to signal that mandatory input\nparameters are missing or have incorrect syntax.\n\n\nYou can also use RaiseFault in a fault rule if you want to detect an error during the processing of a\nfault. For example, your fault handler itself could cause an error that you want to signal by using RaiseFault.\n\nFurther reading\n---------------\n\n- [Handling Faults](/apigee/docs/api-platform/fundamentals/fault-handling)\n- [RaiseFault policy](/apigee/docs/api-platform/reference/policies/raise-fault-policy)\n- [Community discussion on Fault Handling Patterns](https://community.apigee.com/articles/47312/an-improved-pattern-for-fault-handling.html)"]]
