오류 및 오류 해결

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

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

이 페이지의 나머지 부분에서는 오류 구조를 설명하고, 특정 오류 코드를 나열하고, 오류 해결 방법을 제안합니다.

JSON 요청의 오류 응답 구조는 다음과 같습니다.

{
  "error": {
    "code": "integer",
    "message": "string",
    "status": "string"
  }
}

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

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

JSON 요청에 따른 오류 응답의 예는 다음과 같습니다.

{
  "error": {
    "code": 400,
    "message": "Key path is incomplete: [Person: null]",
    "status": "INVALID_ARGUMENT"
  }
}

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

오류 코드

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

표준 오류 코드 설명 권장 작업
ABORTED 요청이 다른 요청과 충돌했음을 나타냅니다. 비트랜잭션 커밋의 경우:
요청을 다시 시도하거나 항목을 구조화하여 경합을 줄입니다.

트랜잭션 커밋의 일부인 요청의 경우:
전체 트랜잭션을 다시 시도하거나 항목을 구조화하여 경합을 줄입니다.
ALREADY_EXISTS 요청이 이미 있는 항목을 삽입하려 했음을 나타냅니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
DEADLINE_EXCEEDED 서버의 기한을 초과했습니다. 지수 백오프를 사용하여 다시 시도하세요.
FAILED_PRECONDITION 요청의 전제조건이 충족되지 않았음을 나타냅니다. 오류 응답의 메시지 필드는 미충족한 전제조건에 대한 정보를 제공합니다. 실행한 쿼리가 색인을 필요로 하나 아직 정의되지 않은 경우 이러한 오류가 발생할 수 있습니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
INTERNAL 서버에서 오류를 반환했습니다. 이 요청을 두 번 이상 재시도하지 마세요.
INVALID_ARGUMENT 요청 매개변수에 잘못된 값이 있음을 나타냅니다. 오류 응답의 메시지 필드에서 어떤 값이 잘못되었는지에 대한 정보를 제공합니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
NOT_FOUND 요청이 존재하지 않는 항목의 업데이트를 시도했음을 나타냅니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
PERMISSION_DENIED 사용자에게 요청할 권한이 없음을 나타냅니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
RESOURCE_EXHAUSTED 프로젝트가 할당량 또는 리전/멀티 리전 용량을 초과했음을 나타냅니다. 프로젝트 할당량을 초과하지 않았는지 확인하세요. 프로젝트 할당량을 초과한 경우 문제를 해결하지 않은 상태로 다시 시도하지 마세요.

그렇지 않으면 지수 백오프를 사용하여 다시 시도하세요.
UNAUTHENTICATED 요청에 올바른 사용자 인증 정보가 없음을 나타냅니다. 문제를 해결하지 않은 상태로 다시 시도하지 마세요.
UNAVAILABLE 서버에서 오류를 반환했습니다. 지수 백오프를 사용하여 다시 시도하세요.