DynamoDB 관련 오류 처리

이 단원에서는 런타임 오류와 그러한 오류를 처리하는 방법을 설명합니다. 또한 Amazon DynamoDB 관련 오류 메시지 및 코드를 설명합니다. 모든 AWS 서비스에 적용되는 일반적인 오류 목록은 액세스 관리를 참조하세요.

오류 구성 요소

프로그램이 요청을 보내면 DynamoDB는 요청 처리를 시도합니다. 요청이 성공하면 DynamoDB는 요청된 작업의 결과와 함께 HTTP 성공 상태 코드(200 OK)를 반환합니다.

요청이 실패하면 DynamoDB는 오류를 반환합니다. 오류에는 세 가지 구성 요소가 있습니다.

• HTTP 상태 코드(예: 400).

• 예외 이름(예: ResourceNotFoundException).

• 오류 메시지(예: Requested resource not found: Table: tablename not found).

AWS SDK는 사용자가 적절한 조치를 취할 수 있도록 애플리케이션에 오류를 전파합니다. 예를 들어 Java 프로그램에서는 ResourceNotFoundException을 처리하기 위해 try-catch 로직을 작성할 수 있습니다.

AWS SDK를 사용하지 않는 경우 DynamoDB에서 하위 수준 응답의 콘텐츠를 구문 분석해야 합니다. 다음은 이러한 응답의 예입니다.

HTTP/1.1 400 Bad Request
x-amzn-RequestId: LDM6CJP8RMQ1FHKSC1RBVJFPNVV4KQNSO5AEMF66Q9ASUAAJG
Content-Type: application/x-amz-json-1.0
Content-Length: 240
Date: Thu, 15 Mar 2012 23:56:23 GMT

{"__type":"com.amazonaws.dynamodb.v20120810#ResourceNotFoundException",
"message":"Requested resource not found: Table: tablename not found"}

트랜잭션 오류

트랜잭션 오류에 대한 자세한 내용은 DynamoDB의 트랜잭션 충돌 처리 섹션을 참조하세요.

오류 메시지 및 코드

다음은 DynamoDB가 반환하는 예외 목록을 HTTP 상태 코드를 기준으로 그룹화한 목록입니다. 재시도 가능?이 예라면 동일한 요청을 다시 제출할 수 있습니다. 재시도 가능?이 아니요라면 새로운 요청을 제출하기 전에 클라이언트 측에서 문제를 해결해야 합니다.

HTTP 상태 코드 400

HTTP 400 상태 코드는 인증 실패, 필수 파라미터 누락, 테이블의 할당 처리량 초과 등 요청에 문제가 있음을 의미합니다. 요청을 다시 제출하기 전에 애플리케이션의 문제를 해결해야 합니다.

AccessDeniedException

메시지: 액세스가 거부되었습니다.

클라이언트가 요청에 정확히 서명하지 않았습니다. AWS SDK를 사용 중인 경우 요청에 자동으로 서명됩니다. 그렇지 않은 경우 AWS 일반 참조의 서명 버전 4 서명 프로세스로 이동하세요.

재시도 가능? 아니요

ConditionalCheckFailedException

메시지: 조건부 요청이 실패했습니다.

false로 평가된 조건을 지정했습니다. 예를 들어 어떤 항목에서 조건부 업데이트 수행을 시도했지만 속성의 실제 값이 조건에서 예상되는 값과 일치하지 않았을 수 있습니다.

재시도 가능? 아니요

IncompleteSignatureException

메시지: 요청 서명이 AWS 표준을 준수하지 않습니다.

요청 서명에 일부 필요한 구성 요소가 빠져있습니다. AWS SDK를 사용 중인 경우 요청에 자동으로 서명됩니다. 그렇지 않은 경우 AWS 일반 참조의 서명 버전 4 서명 프로세스로 이동하세요.

재시도 가능? 아니요

ItemCollectionSizeLimitExceededException

메시지: 그룹 크기 제한이 초과됐습니다.

로컬 보조 인덱스가 포함된 테이블에서 동일한 파티션 키 값의 항목 그룹이 최대 크기 제한 10GB를 초과하였습니다. 항목 그룹에 대한 자세한 내용은 로컬 보조 인덱스의 항목 컬렉션 단원을 참조하세요.

재시도 가능? 예

LimitExceededException

메시지: 임의 구독자의 작업이 너무 많습니다.

동시 제어 플레인 작업이 너무 많습니다. CREATING, DELETING 또는 UPDATING 상태의 누적 테이블 및 인덱스 수는 500을 초과할 수 없습니다.

재시도 가능? 예

MissingAuthenticationTokenException

메시지: 요청에는 유효한(등록된) AWS 액세스 키 ID가 포함되어야 합니다.

요청이 필요한 인증 헤더를 포함하지 않았거나 잘못된 형식입니다. DynamoDB 하위 수준 API 섹션을 참조하세요.

재시도 가능? 아니요

ProvisionedThroughputExceededException

메시지: 테이블 또는 하나 이상의 글로벌 보조 인덱스에게 허용되는 최대 프로비저닝된 처리량을 초과하였습니다. 프로비저닝된 처리량과 소비한 처리량의 성능 지표를 보려면 Amazon CloudWatch 콘솔을 여세요.

예: 요청량이 너무 높습니다. DynamoDB용 AWS SDK가 이 예외를 수신하는 요청을 자동으로 재시도합니다. 재시도 대기열이 너무 많아 완료하지 못하는 경우를 제외하고 결국 요청이 성공합니다. 오류 재시도 횟수 및 지수 백오프를 사용하여 요청 빈도를 줄입니다.

재시도 가능? 예

RequestLimitExceeded

메시지: 처리량이 계정에 대한 현재 처리량 한도를 초과합니다. 한도 증가를 요청하려면 AWS Support(https://aws.amazon.com/support)에 문의하세요.

예: 온디맨드 요청량이 허용된 계정 처리량을 초과했으며 더 이상 테이블의 크기를 조정할 수 없습니다.

재시도 가능? 예

ResourceInUseException

메시지: 변경하려는 리소스가 현재 사용 중입니다.

예: 기존 테이블을 다시 생성하려고 하거나, 또는 현재 CREATING 상태인 테이블을 삭제하려고 했습니다.

재시도 가능? 아니요

ResourceNotFoundException

메시지: 요청한 리소스를 찾을 수 없습니다.

예제: 요청한 테이블이 존재하지 않거나 너무 일찍 CREATING 상태가 되었습니다.

재시도 가능? 아니요

ThrottlingException

메시지: 요청량이 허용 처리량을 초과하였습니다.

이 예외는 THROTTLING_EXCEPTION 상태 코드와 함께 AmazonServiceException 응답으로 반환됩니다. 제어 플레인 API 작업을 너무 빠르게 수행하는 경우 이 예외가 반환될 수 있습니다.

요청 속도가 너무 높으면 온디맨드 모드를 사용하는 테이블의 경우 모든 데이터 플레인 API 작업에 대해 이 예외가 반환될 수 있습니다. 온디맨드 규모 조정에 대한 자세한 내용은 초기 처리량 및 규모 조정 속성 섹션을 참조하세요.

재시도 가능? 예

UnrecognizedClientException

메시지: 액세스 키 ID 또는 보안 토큰이 잘못되었습니다.

요청 서명이 잘못되었습니다. 가장 가능성이 높은 원인은 잘못된 AWS 액세스 키 ID 또는 보안 키입니다.

재시도 가능? 예

ValidationException

메시지: 발생하는 구체적 오류에 따라 다릅니다

이 오류는 필수 파라미터의 누락, 값의 범위 이탈 또는 일치하지 않는 데이터 형식 등 몇 가지 이유로 발생할 수 있습니다. 오류 메시지에는 요청에서 오류를 일으킨 특정 부분에 대한 정보가 포함됩니다.

재시도 가능? 아니요

HTTP 상태 코드 5xx

HTTP 5xx 상태 코드는 AWS가 해결해야 하는 문제를 나타냅니다. 이것은 일시적 오류일 수 있으므로 성공할 때까지 요청을 다시 시도할 수 있습니다. 그렇지 않은 경우 AWS Service Health Dashboard에서 서비스 운영 문제가 있는지 확인하세요.

자세한 내용은 Amazon DynamoDB에서 HTTP 5xx 오류를 해결하려면 어떻게 해야 하나요?를 참조하세요.

InternalServerError (HTTP 500)

DynamoDB에서 요청을 처리할 수 없습니다.

재시도 가능? 예

참고

항목 작업 시 내부 서버 오류가 발생할 수 있습니다. 이러한 오류는 테이블 수명 동안 예상됩니다. 실패한 요청은 즉시 다시 시도할 수 있습니다.

쓰기 작업에 대한 상태 코드 500을 수신하면 작업이 성공했거나 실패했을 수 있습니다. 쓰기 작업이 TransactWriteItem 요청이면 작업을 다시 시도해도 좋습니다. 쓰기 작업이 PutItem, UpdateItem 또는 DeleteItem 같은 단일 항목 쓰기 요청인 경우 작업을 다시 시도하기 전에 애플리케이션이 항목의 상태를 읽어야 합니다. 그리고 DynamoDB 조건 표현식 CLI 예제를 사용하여 이전 작업의 성공 여부와 관계없이 재시도한 후에도 항목이 올바른 상태로 유지되도록 해야 합니다. 멱등성이 쓰기 작업의 요구 사항인 경우 동일한 작업을 수행하려는 여러 시도를 명확하게 하기 위해 ClientRequestToken을 자동으로 지정하여 멱등원 요청을 지원하는 TransactWriteItem을 사용하세요.

ServiceUnavailable (HTTP 503)

DynamoDB를 현재 사용할 수 없습니다. (이것은 일시적 상태여야 합니다.)

재시도 가능? 예

애플리케이션에서의 오류 처리

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

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

또한 응답에서 Request ID도 확인해야 합니다. 문제 진단을 위해 AWS Support와 협력해야 하는 경우 Request ID가 도움이 될 수 있습니다.

오류 재시도 횟수 및 지수 백오프

DNS 서버, 스위치, 로드 밸런서 등 수많은 네트워크 구성 요소는 요청이 이루어지는 모든 단계에서 오류를 일으킬 수 있습니다. 네트워크 환경에서는 클라이언트 애플리케이션의 재시도 기술이 이러한 오류 응답을 처리하는 데 가장 많이 사용되고 있습니다. 이 기술은 애플리케이션의 안정성을 개선합니다.

AWS SDK는 모두 재시도 로직을 자동으로 구현합니다. 재시도 파라미터를 필요에 따라 수정할 수 있습니다. 예를 들어 오류가 발생할 때 재시도가 허용되지 않는 fail-fast 전략을 필요로 하는 Java 애플리케이션을 고려해 보세요. AWS SDK for Java의 경우, ClientConfiguration 클래스를 사용하고 maxErrorRetry 값으로 0을 입력하면 재시도가 비활성화됩니다. 자세한 내용은 해당 프로그래밍 언어의 AWS SDK 설명서를 참조하세요.

AWS SDK를 사용하지 않을 때는 서버 오류(5xx)가 수신된 최초 요청을 재시도해야 합니다. 하지만 클라이언트 오류(4xx, ThrottlingException 또는 ProvisionedThroughputExceededException 제외)는 요청 자체를 수정하여 문제를 해결해야만 재시도가 가능합니다.

간단한 재시도 방법 외에도 각각의 AWS SDK는 흐름 제어가 탁월한 지수 백오프 알고리즘을 구현합니다. 지수 백오프의 기본 개념은 오류 응답이 연이어 나올 때마다 재시도 간 대기 시간을 점진적으로 늘린다는 것입니다. 예를 들어 첫 번째 재시도 전에는 최대 50밀리초, 두 번째 재시도 전에는 최대 100밀리초, 그리고 세 번째 전에는 최대 200밀리초를 기다리는 방식입니다. 하지만 1분 후에도 요청이 실패하면 요청량이 아니라 할당 처리량을 초과하는 요청 크기가 원인일 수도 있습니다. 따라서 약 1분 정도에서 멈추도록 최대 재시도 횟수를 설정하세요. 요청이 실패하면 프로비저닝된 처리량 옵션을 살펴보는 것이 좋습니다.

참고

AWS SDK는 자동 재시도 로직과 지수 백오프를 구현합니다.

대부분의 지수 백오프 알고리즘은 지터(임의 지연)를 사용하여 연쇄 충돌을 방지합니다. 이 경우에는 이런 충돌을 방지하는 것이 아니므로 이 난수를 사용할 필요가 없습니다. 하지만 동시 클라이언트를 사용하는 경우에는 지터가 보다 빠른 요청 성공에 도움이 될 수 있습니다. 자세한 내용은 지수 백오프 및 지터 블로그 게시물을 참조하세요.

일괄 작업 및 오류 처리

DynamoDB 하위 수준 API는 읽기와 쓰기에 대한 배치 작업을 지원합니다. BatchGetItem은 하나 이상의 테이블에서 항목을 읽고 BatchWriteItem은 하나 이상의 테이블에 항목을 추가하거나 삭제합니다. 이 배치 작업은 다른 배치가 아닌 DynamoDB 작업 주위의 래퍼로 구현됩니다. 즉, BatchGetItem은 각 항목마다 한 번씩 GetItem을 일괄 방식으로 불러옵니다. 마찬가지로 BatchWriteItem은 각 항목마다 상황에 맞게 DeleteItem 또는 PutItem을 일괄 방식으로 불러옵니다.

배치 작업은 처리 도중 개별 요청의 오류를 허용할 수 있습니다. 예를 들어 BatchGetItem 요청으로 항목 5개를 읽어온다고 가정하겠습니다. 이때 기본 GetItem 요청 일부가 실패하더라도 전체 BatchGetItem 작업이 실패하지는 않습니다. 그러나 5개 읽기 작업 모두 실패하면 전체 BatchGetItem이 실패합니다.

배치 작업은 실패한 요청 각각에 대한 정보를 반환하므로 사용자가 문제를 진단하고 작업을 재시도할 수 있습니다. BatchGetItem의 경우 해당하는 테이블 및 기본 키가 응답의 UnprocessedKeys 값으로 반환됩니다. BatchWriteItem에서도 비슷한 정보가 UnprocessedItems로 반환됩니다.

읽기 또는 쓰기 작업이 실패할 수 있는 가장 큰 원인은 병목 현상입니다. BatchGetItem일 때는 일괄 요청에 포함된 하나 이상의 테이블에 작업을 지원할 만큼 충분한 읽기 용량이 할당되지 않은 경우입니다. 그리고 BatchWriteItem일 때는 하나 이상의 테이블에 충분한 쓰기 용량이 프로비저닝되지 않은 경우입니다.

DynamoDB가 미처리 항목을 반환하면 해당 항목에 대해 배치 작업을 재시도해야 합니다. 하지만 지수 백오프 알고리즘 사용을 강력히 권장합니다. 배치 작업을 바로 재시도하면 각 테이블의 병목 현상으로 인해 원인이 된 읽기 또는 쓰기 요청이 다시 실패할 수 있습니다. 하지만 지수 백오프를 사용하여 배치 작업을 지연시키면 일괄에 포함된 각 요청 작업이 성공할 가능성이 훨씬 높습니다.