本頁面由 Cloud Translation API 翻譯而成。

處理錯誤

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

當 API Proxy 處理應用程式發出的要求時，可能會發生許多錯誤狀況。適用對象例如，API Proxy 在與後端服務通訊時可能會遇到網路問題應用程式可能會顯示過期的憑證，要求訊息可能也未正確設定格式，保持開啟。

在用戶端應用程式呼叫 API Proxy 時發生錯誤時，系統會將錯誤訊息傳回用戶端。根據預設，用戶端會收到通常不含詳細資料的隱密錯誤訊息，或指引。但如果您想以更實用的自訂訊息取代預設錯誤訊息，您甚至必須設定自訂錯誤以及 Edge 中處理方式

此外，透過自訂錯誤處理功能，您也可以新增訊息記錄等功能錯誤。

在我們討論將自訂錯誤處理機制導入 API Proxy 之前，建議您瞭解發生錯誤的原因，以及 API Proxy 如何回應這些錯誤。

影片

請觀看以下影片，進一步瞭解錯誤處理方式。

影片	說明
簡介：錯誤處理和錯誤流程	瞭解錯誤處理方式，以及 API Proxy 發生錯誤時會發生什麼事。
處理錯誤錯誤規則	瞭解如何使用錯誤規則處理錯誤。
調高自訂值使用 flaFault 政策來處理錯誤	在 API 執行階段使用 PromoteFault 政策引發自訂錯誤。
定義錯誤 API Proxy 與目標端點中的規則	在 API Proxy 和目標端點中定義錯誤規則，並瞭解差異在於
瞭解錯誤規則的執行順序	瞭解 API Proxy 和目標中錯誤規則的執行順序端點。
定義預設錯誤規則	定義預設錯誤規則來處理 API 中的一般錯誤。

錯誤發生方式

首先，我們會簡單說明會「如何」發生。瞭解錯誤發生的原因有助於規劃在要導入自訂錯誤處理的不同情況中。

自動錯誤

在下列情況中，API Proxy 會自動擲回錯誤：

政策會擲回錯誤。舉例來說，如果 API 呼叫傳送過期的金鑰， VerifyAPIKey 政策會自動擲回錯誤。或者 API 呼叫次數超過特定限制時，配額政策或 SpikeArrest 政策會發生錯誤。 (請參閱政策錯誤參考資料，錯誤政策可能擲回的類型)。
API Proxy 訊息流程發生問題，例如轉送錯誤。
導致後端發生錯誤，例如因通訊協定層級故障而導致 HTTP 錯誤，以及傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 錯誤或無法使用的目標服務
發生系統層級的故障，例如記憶體不足例外狀況。

如要進一步瞭解這些錯誤，請參閱本主題中的錯誤分類。

自訂錯誤

在未自動發生錯誤的情況下，您可能需要擲回自訂錯誤。的例如，如果回應包含「unavailable」一詞，或 HTTP 狀態碼大小較大 201 年。方法很簡單，只要在執行 API Proxy 流程

您可以對 API Proxy 流程新增 PromoteFault 政策，做法和執行任何其他政策相同。於以下 Proxy 設定範例，Raise-Fault-1 政策已附加至 TargetEndpoint 回應。如果「無法使用」字樣回應服務後，RAault 政策會執行並擲回錯誤。

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

這只是示範，您可以擲回自訂錯誤。接下來 FaultRules vs. 上述 flaFault 政策中的 PromoteFault 政策專區。

如需更多範例，請參閱 Apigee 社群論壇中的貼文：

在 PromoteFault 中參照 JavaScript 變數

API Proxy 發生錯誤時的處理方式

Proxy 擲回錯誤時的情形如下：

結束 Proxy 管道

無論 API Proxy 發生錯誤的原因為何，系統都會結束一般流程管道，並將錯誤訊息傳回用戶端應用程式。API Proxy 進入錯誤狀態，無法將處理程序傳回一般流程管道。

舉例來說，假設某個 API Proxy 在 ProxyEndpoint 中具有下列順序的政策要求：

驗證 API 金鑰
配額
從 JSON 到 XML

如果 API 金鑰驗證期間發生錯誤，API Proxy 就會進入錯誤狀態。未執行配額和 JSON 到 XML 政策，Proxy 不會繼續執行 TargetEndpoint，並將錯誤訊息傳回用戶端應用程式。

檢查 FaultRules

在錯誤狀態中，API Proxy 也會檢查是否出現下列情況 (依序) 將預設錯誤訊息傳回用戶端應用程式之前，請先選取 API Proxy 設定：

<FaultRules> 區段，其中包含會根據您定義。
<DefaultFaultRule> 區段，用於觸發預設值錯誤訊息：
- 未定義任何<FaultRules>。
- 未執行任何現有 <FaultRules>。
- <AlwaysEnforce> 元素已設為 true。

基本上，API Proxy 可讓您傳回自訂的錯誤訊息觸發其他邏輯如果 Proxy 找不到這些部分，或是這些部分不存在，但沒有任何自訂 fault 已觸發，Proxy 會傳送自己的 Edge 產生的預設訊息。

簡易錯誤處理範例

首先從簡單的範例開始，也就是對 API Proxy 的呼叫並未包含必要的 API 鍵。根據預設，系統會將下列回應傳回用戶端應用程式：

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

您的 API 使用者或許可以找出錯誤訊息，但可能無法。許多預設選項錯誤更細微且難以分辨。

API 開發人員當然可以根據無論是 iOS 應用程式開發人員或內部測試，最終都會收到錯誤訊息群組，以有各自的錯誤訊息格式要求。

以下是如何建立自訂錯誤訊息來處理這項錯誤的基本範例。這個需要 1) 定義自訂訊息的政策，以及 2) 執行政策的 FaultRule 當 Proxy 進入錯誤狀態時。

1. 建立政策定義自訂訊息

首先，請建立定義自訂錯誤訊息的政策。您可以使用任何類型的政策例如 AssignMessage 政策，您可以設定酬載和選用的 HTTP 標頭，例如狀態碼以及原因語句「指派訊息」功能相當適合用於這類用途。可讓您控制訊息酬載以及設定其他 HTTP 原因詞組，並新增 HTTP 標頭。

請勿在 API Proxy 的任何流程中附加政策。只是單純存在於 Proxy 軟體包如要在管理 UI Proxy 編輯器中執行這項操作，請前往「開發」分頁，然後在導覽窗格，按一下政策列上的 + 圖示。

這可以讓您建立政策，而不必附加至 API Proxy 的流程。政策未附加至任何流程的標記會標記為「卸離」「政策」清單中的圖示。

以下是 AssignMessage 政策的範例：

傳回 JSON 訊息。
設定 HTTP 狀態碼 (911)，這是顯然不存在的狀態碼說明您可以的靈活性)。狀態碼會顯示在 HTTP 標頭中。
設定 HTTP 原因詞組 (取代預設的「未經授權」原因詞組)。缺少 API 金鑰錯誤)。在 HTTP 中，狀態碼旁邊會顯示原因詞組標題。
建立並填入名為 invalidKey 的新 HTTP 標頭。

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

執行這項政策時，對用戶端應用程式的回應會如下所示。請將其與稍早顯示的預設回應進行比較。

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

沒錯，這有點傻，但畫面中卻顯示出無限可能。至少現在是開發人員收到訊息，知道他們忘了加入 API 金鑰做為查詢參數。

但這項政策的執行方式為何？下一部分說明瞭自己。

2. 建立 <FaultRule>觸發政策的

在以下頻道的 <ProxyEndpoint> 或 <TargetEndpoint> 部分中：因此請新增一個 <FaultRules> XML 區塊，其中包含一個或多個個別 <FaultRule> 版面。每個 FaultRule 都代表不同的處理錯誤在這個簡單的範例中，我們僅使用一個 FaultRule 來說明模型的構成、

您應該一併新增 <DefaultFaultRule> 來提供自訂的一般錯誤訊息。

範例

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

重點：

FaultRules 是在 ProxyEndpoint 中定義。這很重要，深入瞭解 ProxyEndpoint 中的 FaultRules 和稍後的 TargetEndpoint 部署。
<Name>：要執行的政策名稱。名稱來自政策在父項元素上的 name 屬性，如政策範例
<Condition> - 邊緣評估條件和只有在條件為 true 時才會執行政策。如果有多個 FaultRules 的值為 true，Edge 會執行第一個結果為 true。(重要事項： FaultRules 的評估順序 (由上至下或由上至頂端) 有所不同 TargetEndpoint 和 ProxyEndpoint，如多個 FaultRules 和執行邏輯」一節)。如果沒有包含條件，FultRule 會自動設為 true但這不是最佳做法。每個 FaultRule 都應有專屬的值。

注意：如畫面所示，步驟可以有專屬的「內部」決定是否執行政策的條件。(詳情請參閱 Multiple FaultRules and 執行邏輯一節)。但踏步與是否執行 FaultRule 無關。邊看邊看只有「外部」FaultRule 條件用於判斷要執行哪個 FaultRule。
<DefaultFaultRule> - 如果沒有任何自訂 FaultRule 系統會執行 <DefaultFaultRule>，傳送較通用的，而不是由 Edge 生成的簡訊預設訊息。A 罩杯 <DefaultFaultRule> 也可以擁有 <Condition>，但在大部分的情況都不會納入，因為您希望系統在任何最後執行時，就執行任何動作度假村。

DefaultFaultRule 通常是用來傳回任何發生未預期的錯誤。例如，訊息會包含技術支援服務這個預設回應有兩個目的方便開發人員使用的資訊，同時模糊處理後端網址可能用來入侵系統

多項 FaultRules 和執行邏輯

在簡易錯誤處理範例一節中，我們使用了一個簡易範例單一 FaultRule 和條件的組合。在實際的 API 專案中，包含所有可能的錯誤發生這種情形時，您可能需要同時擁有多個 FaultRules 和 DefaultFaultRules 《<ProxyEndpoint>》和《<TargetEndpoint>》。最終當 API Proxy 進入錯誤狀態時，只會執行一個 FaultRule。

本節說明 Edge 處理 FaultRules 時採用的邏輯，該邏輯是從函式抵達執行單一 FaultRule，以執行「內部」步驟條件會在其 FaultRule 時處理本節也會說明在 <ProxyEndpoint>對<TargetEndpoint>，用於說明 FaultRules 和 PromoteFault 政策之間的關係。

FaultRules 執行

注意： 「外部」和「inner」條件

本主題指的是「outer」以及內部條件您也可以將其視為「FaultRule」以及「Step」條件。兩者的差異很重要。以下為包含 outer FaultRule 條件和內部步驟條件的 FaultRule。我們將討論本節的差異

<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <!-- Inner (Step) condition. Only gets executed if 
                     the FaultRule is executed. -->
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <!-- Outer (FaultRule) condition. Edge evaluates this 
                 to determine whether or not to execute 
                 the FaultRule. -->
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>

簡單來說，當 API Proxy 進入錯誤狀態時，Edge 使用的邏輯如下。請注意，在 ProxyEndpoint 中評估 FaultRules 和 TargetEndpoint，

邊緣會依據不同因素，在 ProxyEndpoint 或 TargetEndpoint 中評估 FaultRules 發生錯誤的位置：
- ProxyEndpoint - Edge 開頭是 bottom 設定 XML 中的 <FaultRule> 並向上運作，以評估每個 <FaultRule> 的 <Condition> (「外部」而不是「內部」<Step> 條件)。
- TargetEndpoint - Edge 開頭是 top <FaultRule> 並繼續運作，目前評估每個 <FaultRule> 的 <Condition> (「外部」而不是「內部」<Step> 條件)。
執行條件為 true 的第一個 FaultRule。如果 FaultRule 沒有條件，預設為 true
- 執行 FaultRule 時，系統會依序評估 FaultRule 中所有步驟，編輯設定系統會自動執行沒有條件的步驟 (系統會執行政策) 以及具有 <Condition> 的值為「true」(判斷為「false」的條件則並非如此) 執行)。
- 如果執行了 FaultRule，卻未執行 FaultRule 中的步驟 (因為條件的值為「false」，則 Edge 產生的預設錯誤訊息會傳回到用戶端應用程式。<DefaultFaultRule>「不會」執行。因為 Edge 已執行其一個 FaultRule
  
  注意：如果 <DefaultFaultRule> 含有子項元素 <AlwaysEnforce>true</AlwaysEnforce> 即使已執行 FaultRule，仍會執行 DefaultFaultRule。
  不過，有些情況並非如此。如果除了 DefaultFaultRule 叫用 PromoteFault 政策，DefaultFaultRule 不會即使 <AlwaysEnforce> 元素中的 <DefaultFaultRule> 標記為 true。
如果沒有執行 FaultRule，則 Edge 會執行 <DefaultFaultRule>，如果。

以下是內嵌註解的示例。

ProxyEndpoint 執行作業

ProxyEndpoint FaultRules 的評估由下而上，因此請開始閱讀最後讀取請參閱下列範例的 FaultRule，並逐步進行處理。上次檢查 DefaultFaultRule，

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

目標端點執行作業

TargetEndpoint FaultRules 評估，從上到下，因此請開始閱讀下例中的 FaultRule 並解決問題。上次檢查 DefaultFaultRule，

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

錯誤規則順序

如上一個範例所示，FultRules 的放置順序為根據錯誤是發生在 ProxyEndpoint 和 TargetEndpoint，

例如：

ProxyEndpoint 順序	TargetEndpoint 順序
在以下範例中，由於評估作業由下至上而執行，系統會執行 FaultRule 3，也就是不會評估 FaultRules 2 和 1。 5. FaultRule 1：FALSE 4. FaultRule 2：TRUE 3. FaultRule 3：TRUE 2. FaultRule 4：FALSE 1. FaultRule：5 FALSE	在以下範例中，由於評估作業是從上往下執行，因此系統會執行 FaultRule 2 這代表 FaultRules 3、4 和 5 不會評估。 1. FaultRule 1：FALSE 2. FaultRule 2：TRUE 3. FaultRule 3：TRUE 4. FaultRule 4：FALSE 5. FaultRule：5 FALSE

ProxyEndpoint 順序

TargetEndpoint 順序

在以下範例中，由於評估作業由下至上而執行，系統會執行 FaultRule 3，也就是不會評估 FaultRules 2 和 1。

5. FaultRule 1：FALSE

4. FaultRule 2：TRUE

3. FaultRule 3：TRUE

2. FaultRule 4：FALSE

1. FaultRule：5 FALSE

在以下範例中，由於評估作業是從上往下執行，因此系統會執行 FaultRule 2 這代表 FaultRules 3、4 和 5 不會評估。

1. FaultRule 1：FALSE

2. FaultRule 2：TRUE

3. FaultRule 3：TRUE

4. FaultRule 4：FALSE

5. FaultRule：5 FALSE

應納入的政策

您可以將 FaultRule 中的政策加進步驟，執行該政策。舉例來說：執行 AssignMessage 政策來設定用戶端應用程式的回應格式，然後記錄訊息建立 MessageLogging 政策。政策將按照您加入的順序執行 (XML 中由上至下)。

錯誤規則「只會」在錯誤狀態觸發 (關於 continueOnError)

標題看起來可能是我們不斷重複的標題，但還是有特定細微差異瞭解 Proxy 錯誤導致 API Proxy 進入錯誤狀態；或者而是不會輸入錯誤狀態：continueOnError 政策。

複習一下：API Proxy 會評估 <FaultRules> 和 <DefaultFaultRule> 只有當 Proxy 進入錯誤狀態時。沒錯換句話說，即使 FaultRule 條件判定為 true，您就不會處於錯誤狀態

不過，以下的例子是發生錯誤，且 Proxy 未進入錯誤狀態。啟用任何政策，您可以為名為 continueOnError 的父項元素設定屬性。該屬性在處理錯誤時相當重要，因為其能如果政策失敗，則 Proxy 會進入錯誤狀態。在大部分的情況下，建議您為預設的 continueOnError="false"，如果系統擷取就會觸發您的自訂錯誤處理程序。不過， continueOnError="true" (例如您不希望 Service 故障時) 呼叫停止 Proxy 執行作業的呼叫，則在下列情況中，Proxy「不會」進入錯誤狀態。政策失敗，Proxy 不會查看您的 FaultRules。

如要瞭解 continueOnError="true" 時的記錄錯誤，請參閱「處理目前流程中的政策錯誤」。

地點定義 FaultRules：ProxyEndpoint 或 TargetEndpoint

當 API Proxy 發生錯誤時，錯誤可能是由 <ProxyEndpoint> (從用戶端應用程式接收或回應要求)，或 <TargetEndpoint> (來自目標服務的要求或回應)。無論那件事 Edge 會尋找 FaultRules 時，就會發生這類錯誤。

舉例來說，如果目標伺服器無法使用 (HTTP 狀態碼 503)，API Proxy 會錯誤狀態出現在 <TargetEndpoint> 回應中的錯誤狀態，以及一般 API Proxy 流量不會繼續前往 <ProxyEndpoint>如果您已定義 FaultRules 卻無法處理該錯誤。<ProxyEndpoint>

我們再看另一個例子如果 <ProxyEndpoint> 上的 PromoteFault 政策是回應觸發錯誤，<TargetEndpoint> 中的 FaultRule 不會取得執行狀態

FaultRules 與 PromoteFault 政策

錯誤規則和舉起 Fault 政策可能出現在表面發音，例如：完成錯誤處理；但事實上，我認為這句話確實符合但這兩者也能搭配運作。這個部分將說明這兩項功能之間的關係。瞭解「雙方」的關係應有助於您需要設計錯誤處理方式，尤其是想要同時使用這兩者時。

簡單來說：

API Proxy 發生錯誤時，一律會評估錯誤規則 時間。

RaiseFault 政策是一種將 API Proxy 置於錯誤狀態的方式就會產生錯誤

舉例來說，假設您要擲回錯誤目標服務的值超過 200，您會在回應中新增 PromoteFault 政策流程網址看起來會像這樣：

<TargetEndpoint name="default">
    <PreFlow name="PreFlow">
...
        <Response>
            <Step>
                <Name>Raise-Fault-1</Name>
<!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                <Condition>(response.status.code GreaterThan "200")</Condition>
            </Step>
        </Response>

PromoteFault 政策也會傳送錯誤訊息至用戶端應用程式。

當 LiftFault 政策觸發錯誤，導致 Proxy 發生錯誤時，會發生什麼事是否可能執行 FaultRule？千萬不要出去。如果 PromoteFault 政策傳回錯誤訊息「且」觸發了 FaultRule，傳回錯誤訊息，系統會傳回什麼內容到用戶端應用程式？

由於 FaultRule 或 DefaultFaultRule 是在 PromoteFault 政策中執行， FaultRule 回應資料勝出。
LiftFault 政策回應資料 (狀態碼、原因詞組或訊息酬載) 為。
如果 PromoteFault 政策和 FaultRule 同時新增自訂 HTTP 標頭，則兩者皆會包含在回應。重複的標頭名稱會建立含有多個值的標頭。

以下舉例說明 LegFault 政策和 FaultRule 設定的內容和傳回用戶端應用程式。這些範例僅供參考，而非最佳做法。

用戶端應用程式會收到：

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

<- 由錯誤規則政策設定的項目：

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

<- PromoteFault 政策會設定此類：

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

注意：如果 <DefaultFaultRule> 含有子系元素 <AlwaysEnforce>true</AlwaysEnforce>，DefaultFaultRule 為一律會執行，即使同時執行了另一個 FaultRule。設有任何酬載和/或標頭系統會將 DefaultFaultRule 中政策的政策傳回用戶端，因為這是最後一個使

建築物條件

條件是 FaultRule 執行作業的關鍵。建立 FaultRule 條件的方式也相同則適用於 Edge 的其他條件，例如用於條件式流量或 PromoteFault 條件。

本節的錯誤規則範例包含外部 FaultRule 條件和內部 Step 條件。

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

政策特有的變數錯誤數

fault.name 和 {policy_namespace}.{policy_name}.failed 變數政策擲回錯誤時可以使用。

fault.name

如果政策失敗，請使用 fault.name 擷取條件中的錯誤變數。例如：

<Condition>(fault.name = "policy_error_name")</Condition>

錯誤名稱會顯示在預設錯誤訊息中。例如，名稱為 FailedToResolveAPIKey。在這個例子中，有一個稱為 fault.name 已設為 FailedToResolveAPIKey 值。

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

因此條件應如下所示：

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

請參閱政策錯誤參考資料。

{policy_namespace}.{policy_name}.failed

政策失敗時，可以使用 *.failed 變數。追蹤對象不同政策的 *.failed 變數範例。如需瞭解政策命名空間，請參閱每個政策參考資料主題中的流程變數。

flaFault 政策：raisefault.failed (對所有 PromoteFault 政策執行相同)
VerifyAPIKey 政策：oauthV2.{policy_name}.failed，用於例如：oauthV2.Verify-API-Key-1.failed
配額政策和 SpikeArrest 政策： ratelimit.{policy_name}.failed，例如 ratelimit.Quota-1.failed

其他可用的變數

API Proxy 進入錯誤狀態時，唯一可在條件中使用的變數是：

失敗的政策變數。
失敗時存在的 HTTP 訊息變數。舉例來說，如果錯誤是在回應中擲回，<TargetEndpoint> 中的 FaultRule 就能使用 HTTP 資料 response.status.code，message.content， error.content 等。如果配額政策失敗，您可以使用變數 ratelimit.{quota_policy_name}.exceed.count。使用追蹤工具和政策參考主題，瞭解可用的變數和 HTTP 資料。

處理錯誤的最佳做法

錯誤處理是 API Proxy 開發的重要架構設計工作。這很重要請花一點時間思考處理錯誤的方式和時間，判斷發生錯誤的原因訊息，以及設計錯誤訊息格式知道這些事情之後 (或說到) 然後採用這些最佳做法，協助您實作錯誤的導入作業。

以下是設計及建構錯誤處理方式的一些最佳做法：

針對每個 FaultRule，請提供「outer」<Condition> (隸屬於 <Step> 元素)。沒有外部條件的錯誤規則會自動評估設為 true「內部」步驟條件「不會」用於判斷 FaultRule 是否為 true 或 false。只有在 Edge 執行包含這些步驟的 FaultRule 時，系統才會評估步驟條件。在 FaultRule 中，通常會設有多個步驟來指派郵件 (或其他) 政策，每個事件都包含步驟條件
為了處理相同類型的多項政策中的錯誤 (例如多個配額) )，針對您可能收到的政策錯誤建立一個 FaultRule。例如：為配額政策中的每個可能錯誤建立 FaultRule，例如 QuotaViolation、InvalidMessageWeight、 StartTimeNotSupported。(請參閱政策錯誤參考資料，政策錯誤。發現其他需要處理的錯誤後，然後將其新增至 FaultRules 中疊代也沒問題 Proxy 重新部署)。這個方法可讓您擷取同一種錯誤，政策會被擲回，因而提高 FaultRules XML 的效率。

如果您需要更精細的錯誤控制項，請使用內部步驟條件。例如：假設您要同時執行兩項政策請將要求流程設為「外部」要在 QuotaViolation 錯誤 (在任一情況下超出配額時，就會擲回此錯誤)。接著設定步驟條件，評估兩個配額中的 exceed.count 變數再檢查有關聯的允許政策只將相關錯誤傳送給用戶端 (開發人員配額超額或全域配額)。設定的範例如下：
```
<FaultRule name="over_quota">

  <Condition>(fault.name = "QuotaViolation")</Condition>
  <Step>
    <Name>developer-over-quota-fault</Name>
    <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
  </Step>
  <Step>
    <Name>global-over-quota-fault</Name>
    <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
  </Step>
</FaultRule>
```
如需其他範例，請參閱這個 Apigee 社群會話串。
使用同一種政策時，如要處理錯誤，請考慮單一錯誤該規則會在該政策失敗時執行，且包含對應至的每個可能錯誤。這樣即可透過單一 FaultRule 提升 XML 效率多個 FaultRules (每個錯誤類型各一個)。例如：
```
<FaultRule name="raise-fault-3">

  <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
  
  <Step>
    <Name>Generic-Key-Fault</Name>
  </Step>
  <Step>
    <Name>Assign-Message-Raise-Fault-1</Name>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
  </Step>
  <Step>
    <Name>Assign-Message-Raise-Fault-2</Name>
    <Condition>(fault.name = "InvalidApiKey")</Condition>
  </Step>
</FaultRule>
```
敬上
注意：使用這個模式時，建議您納入一律會執行 (意即未提供條件)。這是因為由於這個資料庫會運作就會顯示訊息，指出尚未對應到內部條件的錯誤。輸入無條件的步驟優先。如此一來，後續步驟中出現的任何特定錯誤在回應中的優先度。
新增發生錯誤的 FaultRules (用戶端 <ProxyEndpoint>) 或目標側邊 <TargetEndpoint>)。針對符合以下條件的每個政策加入 FaultRules 出現的位置。
您可以在 FaultRules 中執行任何類型的政策，將訊息傳回用戶端應用程式。AssignMessage 政策相當適合用來達成這個目標。你也可以考慮透過 MessageLogging 政策可讓您追蹤錯誤。
將 PromoteFault 政策與 FaultRules 搭配使用時，會協調回應作業 flaFault 政策和 FaultRule 傳回資料時傳回的資料，適用對象舉例來說，如果您的 PromoteFault 政策會重設 HTTP 狀態碼，則不會重設 FaultRule 狀態碼。最糟的情況是，在預設狀態碼會回傳給用戶端應用程式。
<DefaultFaultRule> 執行：
- 如果您希望 <DefaultFaultRule> 在沒有其他項目的情況下一律執行執行 FaultRule 時，請勿在其中加入 <Condition>。
- 如果您希望 <DefaultFaultRule> 在另一個 FaultRule 已執行，請將 <AlwaysEnforce>true</AlwaysEnforce> 子元素。

解鎖圖案集中、可重複使用的錯誤處理

下列 Apigee 社群貼文說明的是集中化錯誤處理模式，重複程式碼：

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

建立 FaultRules

如要新增 FaultRule，請編輯 ProxyEndpoint 的 XML 設定，或 TargetEndpoint，您可以使用 Edge UI 在下列項目的「Code」窗格中進行編輯開發 API 檢視畫面，或編輯定義 ProxyEndpoint 或 TargetEndpoint，

如果您在管理 UI 中建立 FaultRules，請先建立要執行的政策，然後將這些物件新增至 FaultRule 設定即可如果您嘗試儲存參照尚未建立的政策的 FaultRule。)

將政策新增至 FaultRule

雖然您可以在 FaultRule 中放入任何政策，不過您通常會使用 AssignMessage 政策產生錯誤狀況的自訂回應訊息。 AssignMessage 可讓您設定含有酬載、HTTP 狀態碼、標頭的 HTTP 回應，和原因詞組元素

以下範例說明典型的 AssignMessage 政策設定：

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

您現在可以在 FaultRule 中使用這項政策。請注意如何參照 AssignMessage FaultRule 中依名稱指定政策：

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

部署上方設定後，API Proxy 就會執行 AssignMessage 政策呼叫 fault_invalidkey。

您可以在 FaultRule 中執行多項政策，如以下範例所示：

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

政策會依照指定的順序執行。舉例來說，您可以使用 MessageLogging 政策、ExtractVariables 政策、 AssignMessage 政策或 FaultRule。請注意，如果發生下列任一情況，FultRule 處理作業就會立即停止出現：

FaultRule 中的任何政策都會導致錯誤
FaultRule 中任何政策都是 flaFault 類型

定義從 FaultRule 呼叫的自訂錯誤訊息

最佳做法是，相互整合進而為客戶提供一致且實用的資訊。

以下 AssignMessage 政策範例使用 <Payload>： <StatusCode> 和 <ReasonPhase> 標記來定義發生 InvalidApiKey 錯誤時，系統傳回用戶端的錯誤回應 (請參閱先前的 FaultRules) 範例)。

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. 
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

此回應包括：

酬載包含錯誤訊息，以及用於聯絡支援團隊的電子郵件地址。
回應中傳回的 HTTP 狀態碼。
原因詞組，是錯誤的簡短說明。

建立 DefaultFaultRule

DefaultFaultRule 對任何未由再執行一個 FaultRule如果所有 FaultRules 的條件都不相符，則 DefaultFaultRule 會處理錯誤。啟用預設錯誤處理功能，將 <DefaultFaultRule> 標記做為 ProxyEndpoint 或 TargetEndpoint，

例如，以下的 TargetEndpoint 設定定義了叫用預設 FaultRule，名為 ReturnGenericError 的政策：

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

DefaultFaultRule 通常用於傳回任何非預期錯誤的一般錯誤訊息錯誤訊息，例如訊息含有技術支援聯絡資訊。預設回應的目的在於提供適合開發人員的資訊，模糊處理後端網址，或是可能用於入侵系統的其他資訊。

舉例來說，您可以定義下列 AssignMessage 政策傳回一般錯誤：

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

在<AlwaysEnforce> <DefaultFaultRule> 標記會針對每個錯誤執行 DefaultFaultRule 。DefaultFaultRule 一律是最後一個 FaultRule 執行：

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

DefaultFaultRule 其中一種用途是判別錯誤類型，否則就無法判定。例如，您的 API Proxy 因發生錯誤而失敗無法判斷。使用 DefaultFaultRule 叫用下列 AssignMessage 政策。這個政策會將 fault.name 值寫入名為 DefaultFaultHeader 的標頭回應：

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

您可在 Edge 追蹤工具或回應中查看標頭，瞭解導致錯誤。

正在將訊息記錄新增至 PostClientFlow

PostClientFlow 是 Proxy 輸入錯誤後唯一執行的流程時間。只有 MessageLogging 政策能附加至這個流程。系統在回應傳回至用戶端雖然將 MessageLogging 政策附加至這個流程，技術上來說方便您在發生錯誤的情況下記錄資訊。因為無論 Proxy 成功還是失敗，您都可以將訊息記錄放在政策並保證會一律執行。

處理目前流程中的政策錯誤

到目前為止，所有範例都使用 ProxyEndpoint 或 TargetEndpoint 上的 FaultRule 處理錯誤狀態中的任何政策錯誤。這是因為政策的 continueOnError 元素為 false，表示當發生錯誤，控制項會導向錯誤狀態。進入錯誤狀態後控制項無法恢復正常管道，而且您通常會傳回某種錯誤形式傳送給呼叫應用程式的訊息。

不過，如果您將 continueOnError 元素設為 true，政策、控制會保留在目前的流程中，並會在。在目前流程中處理錯誤的好處是：也許能從錯誤中復原，完成要求處理作業。

下方顯示名為 verify-api-key 的 VerifyAPIKey 政策，以及 continueOnError元素已設為 true:

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

如果 API 金鑰遺失或無效，VerifyAPIKey 政策會設定將 oauthV2.verify-api-key.failed 變數設為 true，但正在處理繼續在目前的流程中繼續。

然後，在 ProxyEndpoint 的 PreFlow 中將 VerifyAPIKey 政策新增為步驟：

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>

請注意，PreFlow 的下一步如何使用條件測試是否存在錯誤。如果 VerifAPIKey 政策發生錯誤，系統會執行 FaultInFlow 政策。否則，FaultInFlow 政策是略過。FaultInFlow 政策可以執行許多作業，例如記錄錯誤。嘗試修正錯誤或執行其他動作。

使用 PromoteFault 觸發錯誤政策

您可以隨時在流程中使用 PromoteFault 政策來觸發錯誤。如果 crault 政策執行後會終止目前的流程，並將控管機制轉移至錯誤時間。

flaFault 政策的用途之一是測試其他政策的特定條件可能無法偵測出來在上述範例中，您將 <Condition> 標記新增到導致政策「FaultInFlow」執行的 PreFlow <Step> 標記是否相符。如果 FaultInFlow 是 PromoteFault 政策，則控制權限傳輸到錯誤狀態或者，您可以在流程中插入 PromoteFault 政策，以便偵錯及測試 FaultRules。

當 flaFault 政策觸發錯誤時，您可以使用下列 FaultRule 和條件進行處理：

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

請注意，系統會對名為 RaiseFault 的錯誤進行條件測試。賴起夫政策一律將 fault.name 的值設為 RaiseFault。

自訂 HTTP 錯誤代碼的處理方式再從目標伺服器

前述章節中的範例適用於政策所建立的錯誤，不過，也能針對傳輸層級錯誤建立自訂回應，意即從複製到目標伺服器如要控管 HTTP 錯誤的回應，請將 TargetEndpoint 設定為會處理 HTTP 回應代碼

根據預設，Edge 會將 1xx-3xx 範圍內的 HTTP 回應代碼視為「成功」，而 HTTP 回應代碼範圍介於 4xx-5xx 之間的「failure」(失敗)。這代表來自後端的任何回應傳回 HTTP 回應代碼 4xx-5xx 的服務將自動叫用錯誤狀態，會將錯誤訊息直接傳回給提出要求的用戶端。

您可以為任何 HTTP 回應代碼建立自訂處理常式。舉例來說將 4xx-5xx 範圍中的所有 HTTP 回應代碼視為「失敗」但最好只傳回 5xx 傳回 HTTP 回應代碼 400 和 500 的自訂錯誤訊息。

在接下來的範例中，您將使用 success.codes 屬性設定 TargetEndpoint 將 HTTP 回應代碼 400 和 500 和預設的 HTTP 視為成功代碼。將這些代碼視為成功後，TargetEndpoint 會接手處理回應訊息，而不要叫用錯誤狀態：

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

如範例所示，您可以使用萬用字元，將 success.codes 屬性設為某個範圍的值。

設定 success.codes 屬性覆寫預設值。因此，如果您想將 HTTP 代碼 400 加入預設成功清單程式碼，請將此屬性設為：

<Property name="success.codes">1xx,2xx,3xx,400</Property>

不過，如果您只想將 HTTP 代碼 400 視為成功代碼，請將屬性設為：

<Property name="success.codes">400</Property>

您現在可以定義用於 HTTP 回應代碼 400 和 500 的自訂處理常式，以傳回自訂的傳送給提出要求的應用程式的回應訊息。下列 TargetEndpoint 使用的政策 ReturnError 來處理 HTTP 400 和 500 回應代碼：

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

這項 TargetEndpoint 設定會導致名為 ReturnError 的政策處理每當 TargetEndpoint 遇到 HTTP 回應碼 400 或 500 時就會回應。

錯誤分類

API 服務將錯誤分為以下類別和子類別。

類別	子類別	錯誤名稱	說明
訊息			訊息傳送期間失敗 (不含政策失敗)
	自訂錯誤	{fault_name}	由 API Proxy 使用 PromoteFault 政策明確處理的任何錯誤
	回應碼	InternalServerError，找不到	HTTP 錯誤代碼 5xx、4xx
	轉送失敗	NoRoutesMatched	無法為要求選取已命名的目標端點
	分類失敗	NotFound	要求 URI 與任何 ProxyEndpoint 的任何 BasePath 不符，導致失敗設定 (也就是說，沒有任何 API Proxy 與用戶端應用程式要求中的網址相符)
交通			HTTP 傳輸層級錯誤
	連線能力	ConnectionRefused、ConnectionReset、ConnectionTimeout	建立網路或傳輸層級連線時發生錯誤
	要求驗證	ContentLengthMissing, HostHeaderMissing	每個要求的語意檢查期間都會發生錯誤
	回應驗證	ContentLengthMissing, HostHeaderMissing	每次回應的語意檢查期間都會發生錯誤
	IO 錯誤	SSLHandshakeError、ReadTimeout、ReadError、WriteTimeout、WriteError、ChunkError	用戶端或目標端點的讀取/寫入錯誤、逾時、TLS/SSL 錯誤和區塊化錯誤數
系統			未定義的執行階段錯誤
	記憶體	OutOfMemory、GCOverLimit	記憶體相關故障
	討論串	RogueTaskTerminated	失敗，例如終止執行作業的工作
政策			如要瞭解各種政策類型的錯誤，請參閱政策參考資料：

錯誤一律會附加失敗原因的文字說明。當系統會引發錯誤，填入一組屬性，協助排解問題。一項錯誤包含下列資訊：

原因
使用者定義的自訂屬性