기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 오류 처리
<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 SDK는 적절한 조치를 취할 수 있도록 애플리케이션에 오류를 전파합니다. 예를 들어 Java 프로그램에서는 `ResourceNotFoundException`을 처리하기 위해 `try-catch` 로직을 작성할 수 있습니다.

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 리소스 이름(ARN)을 사용하여 작업을 수행하십시오.  
재시도 가능? 아니요

**GroupFacesInProgressException **  
메시지: *Failed to schedule GroupFaces job. There is an existing group faces job for this collection.*  
기존 작업이 완료된 후에 작업을 재시도해 보십시오.  
재시도 가능? 아니요

**IdempotentParameterMismatchException **  
메시지: *제공된 ClientRequestToken(<Token>)은 이미 사용 중입니다.*  
ClientRequestToken 입력 파라미터가 작업에서 재사용되었지만 하나 이상의 다른 입력 파라미터가 이전의 작업 호출과 다릅니다.  
재시도 가능? 아니요

**ImageTooLargeException **  
메시지: *이미지가 너무 큽니다.*  
입력 이미지의 크기가 허용된 한도를 초과합니다. [DetectProtectiveEquipment](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_DetectProtectiveEquipment.html)를 직접 호출하는 경우 이미지 크기 또는 해상도가 허용된 한도를 초과합니다. 자세한 내용은 [Amazon Rekognition의 가이드라인 및 할당량](limits.md) 단원을 참조하십시오.  
재시도 가능? 아니요

**InvalidImageFormatException **  
메시지: *요청에 잘못된 이미지 형식이 있습니다.*  
제공된 이미지 형식은 지원되지 않습니다. 지원되는 이미지 형식(.JPEG 및 .PNG)을 사용하십시오. 자세한 내용은 [Amazon Rekognition의 가이드라인 및 할당량](limits.md) 단원을 참조하십시오.  
재시도 가능? 아니요

**InvalidPaginationTokenException **  
메시지  
+ *잘못된 토큰*
+ *잘못된 매김 토큰*
요청의 매김 토큰이 잘못되었습니다. 토큰이 만료되었을 수 있습니다.  
재시도 가능? 아니요 

**InvalidParameterException **  
메시지: *요청에 잘못된 파라미터가 있습니다.*  
입력 파라미터가 제약 조건을 위반했습니다. 파라미터를 확인한 다음 API 작업을 다시 호출하십시오.  
재시도 가능? 아니요

**InvalidS3ObjectException **  
메시지:  
+ *요청에 잘못된 S3 객체가 있습니다.*
+ *Unable to get object metadata from S3. Check object key, region and/or access permissions.*
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)을 참조하십시오.  
재시도 가능? 아니요

**LimitExceededException **  
메시지:  
+ *스트림 프로세서의 제한이 계정의 한도(<Current Limit>)를 초과했습니다.*
+ *사용자(<User ARN>)를 위한 열린 작업 <Number of Open Jobs>개. 최대 한도: <Maximum Limit>*
Amazon Rekognition 서비스 제한을 초과했습니다. 예를 들어 너무 많은 Amazon Rekognition Video 작업을 동시에 시작하면서 `StartLabelDetection` 등의 작업을 직접 호출할 경우에는 동시 실행 작업의 수가 Amazon Rekognition 서비스 제한 미만이 될 때까지 `LimitExceededException` 예외(HTTP 상태 코드: 400)가 발생합니다.  
재시도 가능? 아니요

**ProvisionedThroughputExceededException **  
메시지:  
+ *프로비저닝된 속도가 초과되었습니다.*
+ *S3 다운로드 한도가 초과되었습니다.*
요청의 수가 처리량 한도를 초과했습니다. 자세한 내용은 [Amazon Rekognition 서비스 한도](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_rekognition)를 참조하세요.  
한도 증가를 요청하려면 [TPS 할당량 변경을 위한 사례 생성](limits.md#quotas-create-case)의 지침을 따르세요.  
재시도 가능? 예

**ResourceAlreadyExistsException **  
메시지: *모음의 ID(<Collection Id>)가 이미 존재합니다.*  
 지정된 ID의 모음이 이미 존재합니다.  
재시도 가능? 아니요

**ResourceInUseException **  
메시지:  
+ *스트림 프로세서의 이름이 이미 사용 중입니다.*
+ *지정된 리소스가 이미 사용 중입니다.*
+ * 프로세서를 스트림 중지에 사용할 수 없습니다.*
+ *스트림 프로세서를 삭제할 수 없습니다.*
리소스를 사용할 수 있을 때 다시 시도하십시오.  
재시도 가능? 아니요

**ResourceNotFoundException **  
메시지: API 호출에 따라 메시지가 달라집니다.  
지정된 리소스가 존재하지 않습니다.  
재시도 가능? 아니요

**ThrottlingException **  
메시지: *속도를 줄이십시오. 요청 속도가 급증했습니다.*  
요청 증가 속도가 너무 빠릅니다. 요청 속도를 줄이고 조금씩 늘리십시오. 백오프를 지수적으로 수행하고 다시 시도하는 것이 좋습니다. 기본적으로 AWS SDKs 자동 재시도 로직과 지수 백오프를 사용합니다. 자세한 내용은 [AWS에서의 오류 재시도 및 지수 백오프](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) 단원과 [지수 백오프 및 Jitter](http://www.awsarchitectureblog.com/2015/03/backoff.html) 단원을 참조하십시오.  
재시도 가능? 예

**VideoTooLargeException **  
메시지: *비디오 크기 <Video Size>(바이트)가 최대 한도인 <Max Size>바이트를 초과합니다.*  
제공된 미디어의 파일 크기 또는 재생 시간이 너무 크거나 깁니다. 자세한 내용은 [Amazon Rekognition의 가이드라인 및 할당량](limits.md) 단원을 참조하십시오.  
재시도 가능? 아니요

### HTTP 상태 코드 5xx
<a name="error-handling.MessagesAndCodes.http5xx"></a>

HTTP `5xx` 상태 코드는 AWS가 해결해야 하는 문제를 나타냅니다. 일시적 오류일 수 있습니다. 그 경우, 성공할 때까지 요청을 재시도할 수 있습니다. 그렇지 않은 경우 [AWS Service Health Dashboard](https://status.aws.amazon.com/)에서 서비스 운영 문제가 있는지 확인하십시오.

**InternalServerError(HTTP 500) **  
메시지: *내부 서버 오류가 발생했습니다.*  
Amazon Rekognition에 서비스 문제가 발생했습니다. 호출을 다시 시도하세요. 백오프를 지수적으로 수행하고 다시 시도해야 합니다. 기본적으로 AWS SDK는 자동 재시도 로직과 지수 백오프를 사용합니다. 자세한 내용은 [AWS에서의 오류 재시도 및 지수 백오프](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) 단원과 [지수 백오프 및 Jitter](http://www.awsarchitectureblog.com/2015/03/backoff.html) 단원을 참조하십시오.  
재시도 가능? 예

**ThrottlingException(HTTP 500)**  
메시지: *서비스를 사용할 수 없습니다.*  
Amazon Rekognition이 요청을 일시적으로 처리할 수 없습니다. 호출을 다시 시도하세요. 백오프를 지수적으로 수행하고 다시 시도하는 것이 좋습니다. 기본적으로 AWS SDKs 자동 재시도 로직과 지수 백오프를 사용합니다. 자세한 내용은 [AWS에서의 오류 재시도 및 지수 백오프](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) 단원과 [지수 백오프 및 Jitter](http://www.awsarchitectureblog.com/2015/03/backoff.html) 단원을 참조하십시오.  
재시도 가능? 예

## 애플리케이션에서의 오류 처리
<a name="error-handling.Handling"></a>

애플리케이션의 원활한 실행을 위해서는 오류를 발견하여 대응할 수 있는 로직을 추가해야 합니다. 일반적인 접근법에는 `try-catch` 블록 또는 `if-then` 문의 사용이 포함됩니다.

AWS SDK는 자체적으로 재시도 및 오류 검사를 실행합니다. AWS SDK 사용 중에 오류가 발생하면 해당 오류 코드와 설명이 문제 해결에 도움이 될 수 있습니다.

또한 응답에서 `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` - 이 예외는 클라이언트가 서비스로부터 응답을 받을 수 없거나 서비스의 응답을 구문 분석할 수 없는 경우에 발생합니다.