이 페이지에서는 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 또는 프로젝트 할당량을 초과하지 않았는지 확인합니다. 할당량을 초과한 경우 문제를 해결하지 않은 상태로 다시 시도하지 마세요. 그렇지 않으면 지수 백오프를 사용하여 다시 시도하세요. |
UNAUTHENTICATED |
요청에 작업과 관련된 올바른 사용자 인증 정보가 없습니다. | 문제를 해결하지 않은 상태로 다시 시도하지 마세요. |
UNAVAILABLE |
현재 서버를 사용할 수 없습니다. | 지수 백오프를 사용하여 다시 시도하세요. 멱등성이 없는 작업을 재시도하는 것이 항상 안전한 것은 아닙니다. |
UNIMPLEMENTED |
작업이 구현되지 않았거나 이 서비스에서 지원되지 않거나 사용 설정되지 않았습니다. | 문제를 해결하지 않은 상태로 다시 시도하지 마세요. |
UNKNOWN |
서버에서 알 수 없는 오류를 반환했습니다. 오류 정보를 충분히 반환하지 않는 API에서 발생한 오류가 이 오류로 변환될 수 있습니다. | 요청이 안전한지 확인합니다. 그런 다음 지수 백오프를 사용하여 다시 시도하세요. |