本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 錯誤處理
<a name="error-handling"></a>

 本節說明執行時期錯誤和其處理方式。其中也會說明 Amazon Rekognition 特有的錯誤訊息和程式碼。

**Topics**
+ [錯誤元件](#error-handling.Components)
+ [錯誤訊息和錯誤碼](#error-handling.MessagesAndCodes)
+ [應用程式中的錯誤處理](#error-handling.Handling)

## 錯誤元件
<a name="error-handling.Components"></a>

當您的程式傳送請求時，Amazon Rekognition 會嘗試進行處理。如果請求成功，則 Amazon Rekognition 會傳回 HTTP 成功狀態碼 (`200 OK`) 以及所請求操作的結果。

如果請求不成功，Amazon Rekognition 會傳回錯誤。每個錯誤都會有三個元件：
+ HTTP 狀態碼 (例如 `400`)。
+ 例外狀況名稱 (例如 `InvalidS3ObjectException`)。
+ 錯誤訊息 (例如 `Unable to get object metadata from S3. Check object key, region and/or access permissions.`)。

AWS 開發套件會負責將錯誤傳播至應用程式，讓您可以採取適當的動作。例如，在 Java 程式中，您可以撰寫 `try-catch` 邏輯來處理 `ResourceNotFoundException`。

如果您不是使用 AWS SDK，則需要剖析來自 Amazon Rekognition 之下層回應的內容。以下是這類回應的範例：

```
HTTP/1.1 400 Bad Request
Content-Type: application/x-amz-json-1.1
Date: Sat, 25 May 2019 00:28:25 GMT
x-amzn-RequestId: 03507c9b-7e84-11e9-9ad1-854a4567eb71
Content-Length: 222
Connection: keep-alive

{"__type":"InvalidS3ObjectException","Code":"InvalidS3ObjectException","Logref":"5022229e-7e48-11e9-9ad1-854a4567eb71","Message":"Unable to get object metadata from S3. Check object key, region and/or access permissions."}
```

## 錯誤訊息和錯誤碼
<a name="error-handling.MessagesAndCodes"></a>

以下是 Amazon Rekognition 所傳回並依 HTTP 狀態碼進行群組的例外狀況清單。*確定要重試嗎？*為*是*，則可以重新提交相同的請求。*確定要重試嗎？*為*否*，則需要先修正使用者端上的問題，再提交新的請求。

### HTTP 狀態碼 400
<a name="error-handling.MessagesAndCodes.http400"></a>

HTTP `400` 狀態碼表示您的請求有問題。一些問題範例包括驗證失敗、必要參數遺失，或超過資料表的佈建輸送量。您必須先修正應用程式中的問題，再重新提交請求。

**AccessDeniedException **  
訊息：*呼叫 <Operation> 操作時發生錯誤 (AccessDeniedException)：使用者：<User ARN> 未獲授權於資源：<Resource ARN> 上執行：<Operation>。*  
您未獲授權執行動作。使用已獲授權之使用者或 IAM 角色的 Amazon Resource Name (ARN) 來執行操作。  
OK to retry? (確定要重試嗎？) 否

**GroupFacesInProgressException **  
訊息：*無法排程 GroupFaces 任務。此集合有現有的群組表面任務。*  
請在現有任務完成後重試操作。  
OK to retry? (確定要重試嗎？) 否

**IdempotentParameterMismatchException **  
訊息：*ClientRequestToken：您提供的 <Token> 已在使用中。*  
ClientRequestToken 輸入參數重複用於一個操作，但至少有一個其他輸入參數不同於先前對操作的呼叫。  
OK to retry? (確定要重試嗎？) 否

**ImageTooLargeException **  
訊息：*影像大小太大。*  
輸入影像大小超過允許的限制。如果您呼叫 [DetectProtectiveEquipment](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DetectProtectiveEquipment.html)，影像大小或解析度超過允許的限制。如需詳細資訊，請參閱 [Amazon Rekognition 中的準則和配額](limits.md)。  
OK to retry? (確定要重試嗎？) 否

**InvalidImageFormatException **  
訊息：*請求的影像格式無效。*  
不支援所提供的影像格式。請使用支援的影像格式 (.JPEG 和 .PNG)。如需詳細資訊，請參閱 [Amazon Rekognition 中的準則和配額](limits.md)。  
OK to retry? (確定要重試嗎？) 否

**InvalidPaginationTokenException **  
訊息  
+ *無效的字符*
+ *無效的分頁符記*
請求中的分頁符記無效。符記可能已過期。  
OK to retry? (確定要重試嗎？) 否 

**InvalidParameterException **  
訊息：*請求有無效的參數。*  
輸入參數違反限制。請驗證您的參數，然後再次呼叫 API 操作。  
OK to retry? (確定要重試嗎？) 否

**InvalidS3ObjectException **  
訊息：  
+ *請求有無效的 S3 物件。*
+ *無法從 S3 取得物件中繼資料。檢查物件金鑰、區域和/或存取許可。*
Amazon Rekognition 無法存取請求中指定的 S3 物件。如需詳細資訊，請參閱[設定對 S3 的存取：AWS S3 管理存取](https://docs.aws.amazon.com/AmazonS3/latest/dev/s3-access-control.html)。如需故障診斷資訊，請參閱[故障診斷 Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/troubleshooting.html)。  
OK to retry? (確定要重試嗎？) 否

**LimitExceededException **  
訊息：  
+ *超出帳戶的串流處理器限制，限制 - <目前限制>。*
+ * <開啟任務數> 開啟任務，適用於使用者 <使用者 ARN> 最大限制：<最大限制> *
超出 Amazon Rekognition 服務限制。例如，如果您同時啟動太多 Amazon Rekognition Video 任務，啟動操作的呼叫 (例如 `StartLabelDetection`) 將引發 `LimitExceededException` 例外狀況 (HTTP 狀態碼：400)，直到同時執行任務的數量低於 Amazon Rekognition 服務限制。  
OK to retry? (確定要重試嗎？) 否

**ProvisionedThroughputExceededException **  
訊息：  
+ *超過佈建率。*
+ *超過 S3 下載限制。*
請求數超過您的傳輸量限制。如需詳細資訊，請參閱 [Amazon Rekognition服務限制](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_rekognition)。  
若要要求增加限制，請遵循的指示[建立案例以變更 TPS 配額](limits.md#quotas-create-case)。  
OK to retry? (確定要重試嗎？) 是

**ResourceAlreadyExistsException **  
訊息：*集合 ID：<集合 ID> 已存在。*  
 已存在使用指定 ID 的集合。  
OK to retry? (確定要重試嗎？) 否

**ResourceInUseException **  
訊息：  
+ *串流處理器名稱已在使用中。*
+ *指定的資源已在使用中。*
+ *處理器無法用於停止串流。*
+ *無法刪除串流處理器。*
當資源可用時重試。  
OK to retry? (確定要重試嗎？) 否

**ResourceNotFoundException **  
訊息：根據 API 呼叫的不同訊息。  
指定的資源不存在。  
OK to retry? (確定要重試嗎？) 否

**ThrottlingException **  
訊息：*減慢；請求率突然增加。*  
您的請求率增加過快。請減慢並逐漸增加您的請求率。我們建議您以指數方式退避並再試一次。根據預設， AWS SDKs 會使用自動重試邏輯和指數退避。如需詳細資訊，請參閱[在 AWS 中錯誤重試與指數退避](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)和[指數退避和抖動](http://www.awsarchitectureblog.com/2015/03/backoff.html)。  
OK to retry? (確定要重試嗎？) 是

**VideoTooLargeException **  
訊息：*影片大小 (位元組)：<影片大小> 超過最大限制：<最大大小> 位元組。*  
所提供媒體的檔案大小或持續時間太大。如需詳細資訊，請參閱 [Amazon Rekognition 中的準則和配額](limits.md)。  
OK to retry? (確定要重試嗎？) 否

### HTTP 狀態碼 5xx
<a name="error-handling.MessagesAndCodes.http5xx"></a>

HTTP `5xx` 狀態碼指出 AWS必須解決的問題。這可能是暫時性錯誤。如果確實如此，您可以重試請求直到成功。否則，請前往 [AWS 服務運作狀態儀表板](https://status.aws.amazon.com/)，確認服務是否發生任何操作問題。

**InternalServerError (HTTP 500) **  
訊息：*內部伺服器錯誤*  
Amazon Rekognition 發生服務問題。請再次嘗試呼叫。您應以指數方式退避，然後再試一次。依預設， AWS SDK 會使用自動重試邏輯和指數退避。如需詳細資訊，請參閱[在 AWS 中錯誤重試與指數退避](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)和[指數退避和抖動](http://www.awsarchitectureblog.com/2015/03/backoff.html)。  
OK to retry? (確定要重試嗎？) 是

**ThrottlingException (HTTP 500)**  
訊息：*服務無法使用*  
Amazon Rekognition 暫時無法處理請求。請再次嘗試呼叫。我們建議您以指數方式退避並再試一次。根據預設， AWS SDKs 會使用自動重試邏輯和指數退避。如需詳細資訊，請參閱[在 AWS 中錯誤重試與指數退避](https://docs.aws.amazon.com/general/latest/gr/api-retries.html)和[指數退避和抖動](http://www.awsarchitectureblog.com/2015/03/backoff.html)。  
OK to retry? (確定要重試嗎？) 是

## 應用程式中的錯誤處理
<a name="error-handling.Handling"></a>

若要讓您的應用程式順暢執行，您需要新增邏輯來截獲並回應錯誤。一般方式包含使用 `try-catch` 區塊或 `if-then` 陳述式。

AWS 開發套件會執行自己的重試和錯誤檢查。如果您在使用其中一個 AWS 開發套件時發生錯誤，則錯誤碼和說明可以協助您對其進行故障診斷。

您應該也會在回應中看到 `Request ID`。如果您需要與 AWS Support 合作來診斷問題，則 `Request ID` 可能十分有用。

以下 Java 程式碼片段嘗試偵測影像中的物件，並執行早期錯誤處理。(在此情況下，它只會通知請求失敗的使用者。) 

```
try {
    DetectLabelsResult result = rekognitionClient.detectLabels(request);
    List <Label> labels = result.getLabels();

    System.out.println("Detected labels for " + photo);
    for (Label label: labels) {
        System.out.println(label.getName() + ": " + label.getConfidence().toString());
    }
} 
catch(AmazonRekognitionException e) {
    System.err.println("Could not complete operation");
    System.err.println("Error Message:  " + e.getMessage());
    System.err.println("HTTP Status:    " + e.getStatusCode());
    System.err.println("AWS Error Code: " + e.getErrorCode());
    System.err.println("Error Type:     " + e.getErrorType());
    System.err.println("Request ID:     " + e.getRequestId());
}
catch (AmazonClientException ace) {
    System.err.println("Internal error occurred communicating with Rekognition");
    System.out.println("Error Message:  " + ace.getMessage());
}
```

在此程式碼片段中，`try-catch` 建構會處理兩個不同類型的例外狀況：
+ `AmazonRekognitionException`：如果使用者端請求正確地傳輸至 Amazon Rekognition，但 Amazon Rekognition 無法處理請求並改為傳回錯誤回應，將會發生此例外。
+ `AmazonClientException`：如果使用者端無法從服務取得回應，或者如果使用者端無法剖析來自服務的回應，將會發生此例外。