Spanner 오류 코드

이 페이지에서는 Spanner 오류 코드와 이러한 오류를 처리하기 위한 권장 조치를 설명합니다. Spanner를 포함한 Google API는 google.rpc.Code를 통해 정의된 표준 오류 코드를 사용합니다.

Spanner 요청이 성공하면 API는 응답 본문에서 요청된 데이터와 함께 HTTP 200 OK 상태 코드를 반환합니다.

요청이 실패하면 Spanner API는 실패를 일반적으로 식별하는 HTTP 4xx 또는 5xx 상태 코드와 함께 실패를 초래한 오류에 대한 구체적인 정보를 제공하는 응답을 반환합니다.

응답 객체에는 단일 error 필드가 포함되고 값에는 다음 요소가 포함되어 있습니다.

요소 설명
code 요청 실패를 전반적으로 식별하는 HTTP 상태 코드
message 요청 실패에 대한 자세한 정보
status Google API의 표준 오류 코드(google.rpc.Code)입니다. Spanner API에서 반환할 수 있는 코드는 오류 코드에 나열되어 있습니다.

application/x-protobuf 콘텐츠 유형으로 생성된 요청으로 인해 오류가 발생한 경우에는 페이로드로 직렬화된 google.rpc.Status 메시지가 반환됩니다.

오류 코드

오류를 분류하는 좋은 방법은 표준 오류 코드(google.rpc.Code) 값을 검사하는 것입니다. JSON 오류에서 이 코드는 status 필드에 표시됩니다. application/x-protobuf 오류에서는 code 필드에 표시됩니다.

오류 코드 설명 권장 조치
ABORTED 작업이 취소되었습니다. 대개 시퀀서 확인 실패, 트랜잭션 취소 등의 동시 실행 문제가 원인입니다. 요청이 다른 요청과 충돌했음을 나타냅니다. 비트랜잭션 커밋의 경우:
요청을 다시 시도하거나 항목을 구조화하여 경합을 줄입니다.

트랜잭션 커밋의 일부인 요청의 경우:
전체 트랜잭션을 다시 시도하거나 항목을 구조화하여 경합을 줄입니다.
ALREADY_EXISTS 클라이언트에서 만들려고 시도한 항목이 이미 존재합니다(예: 기존 기본 키가 있는 행 삽입). 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
CANCELLED 작업이 취소되었습니다. 대개 호출자에 의해 취소됩니다. 작업을 재시도합니다.
DEADLINE_EXCEEDED 작업을 완료하기 전에 기한이 지났습니다. 기한이 충분한지 조사합니다. 응답이 유용한 실제 시간에 해당하는 기한을 사용하세요. 작업에서 시스템의 상태를 변경하는 경우 작업이 정상적으로 완료되었어도 오류가 반환될 수 있습니다.

도움말은 기한 초과 오류 문제 해결을 참조하세요.
FAILED_PRECONDITION 요청의 전제조건이 충족되지 않아 작업이 거부되었습니다. 오류 응답의 메시지 필드는 충족하지 못한 전제조건에 대한 정보를 제공합니다. 예를 들어 최대 타임스탬프 비활성을 초과한 타임스탬프에서 읽거나 쿼리하는 경우입니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
INTERNAL 서버에서 오류를 반환했습니다. 기본 시스템에서 예상하는 불변성이 손상되었습니다. 오류의 구체적인 상황과 원인을 이해하지 못한 상태에서는 다시 시도하지 마세요.
INVALID_ARGUMENT 클라이언트가 잘못된 값을 지정했습니다. 오류 응답의 메시지 필드에서 어떤 값이 잘못되었는지에 대한 정보를 제공합니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
NOT_FOUND 항목 업데이트, 테이블 또는 열 쿼리와 같이 요청된 일부 항목이 존재하지 않음을 나타냅니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
OUT_OF_RANGE 유효한 범위를 벗어나는 작업을 시도했습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
PERMISSION_DENIED 사용자가 요청을 보낼 권한이 없습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
RESOURCE_EXHAUSTED 일부 리소스가 소진되었습니다.

관리자 영역의 경우, 프로젝트의 할당량을 초과하거나 전체 파일 시스템의 저장 공간이 모두 사용되었을 수 있습니다.

데이터 영역의 경우, Spanner 노드에 과부하가 발생한 경우 이러한 문제가 발생할 수 있습니다.		 관리자 영역의 경우 Spanner 또는 프로젝트 할당량을 초과하지 않았는지 확인합니다. 할당량을 초과한 경우 할당량 상향을 요청하거나 할당량이 재설정될 때까지 기다린 후 다시 시도하세요. 지수 백오프를 사용하도록 재시도를 구성합니다.

데이터 영역의 경우 Spanner 노드의 용량이 초과되지 않았는지 확인합니다. Spanner는 클라이언트 라이브러리에서 이러한 오류를 재시도합니다. 모든 재시도가 실패하면 흐름 제어 메커니즘 오류를 참조하세요.

일반적으로 애플리케이션에 RESOURCE_EXHAUSTED 오류가 발생하면 이 상황을 UNAVAILABLE 오류처럼 처리하고 지수 백오프를 사용해 다시 시도합니다.
UNAUTHENTICATED 요청에 작업과 관련된 올바른 사용자 인증 정보가 없습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
UNAVAILABLE 서버를 사용할 수 없습니다. 지수 백오프를 사용하여 다시 시도하세요. 멱등성이 없는 작업을 재시도하는 것이 항상 안전한 것은 아닙니다.
UNIMPLEMENTED 작업이 구현되지 않았거나 이 서비스에서 지원되지 않거나 사용 설정되지 않았습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
UNKNOWN 서버에서 알 수 없는 오류를 반환했습니다. 오류 정보를 충분히 반환하지 않는 API에서 발생한 오류가 이 오류로 변환될 수 있습니다. 요청이 안전한지 확인합니다. 그런 다음 지수 백오프로 다시 시도합니다.

흐름 제어 메커니즘 오류

Spanner는 다음과 같은 조건에서 흐름 제어 메커니즘을 활성화하여 오버로드로부터 자신을 보호할 수 있습니다.

  • Spanner 노드에서 CPU 사용량이 많습니다. 요청으로 인해 CPU 사용량이 많아지는 것으로 의심되면 CPU 사용률 측정항목을 사용하여 문제를 조사할 수 있습니다.
  • 요청 처리 시간이 늘어나는 부하 집중이 있을 수 있습니다. 요청으로 인해 부하 집중이 발생하는 것으로 의심되면 데이터베이스에서 부하 집중 찾기를 참조하여 문제를 조사하세요. 자세한 내용은 키 시각화 도구를 참조하세요.

흐름 제어 메커니즘은 다음 클라이언트 라이브러리에서 지원됩니다.

흐름 제어 메커니즘을 사용해도 요청이 완료되는 데 걸리는 전체 시간은 늘어나지 않습니다. 이 메커니즘이 없으면 Spanner는 요청을 처리하기 전에 기다렸다가 결국 DEADLINE_EXCEEDED 오류를 반환합니다.

흐름 제어 메커니즘이 활성화되면 Spanner는 재시도할 요청을 클라이언트로 다시 푸시합니다. 재시도에 전체 사용자 제공 기한이 소요되면 클라이언트는 RESOURCE_EXHAUSTED 오류를 수신합니다. 이 오류는 Spanner에서 요청 처리 시간이 너무 길다고 판단하는 경우 반환됩니다. 이 오류는 흐름 제어를 전파하고 Spanner는 내부적으로 재시도를 누적하는 대신 클라이언트에 요청을 다시 시도합니다. 이렇게 하면 Spanner에서 추가 리소스 소비가 누적되는 것을 방지할 수 있습니다.