Package google.rpc

색인

• BadRequest(메시지)
• BadRequest.FieldViolation(메시지)
• Code(열거형)
• ErrorInfo(메시지)
• Help(메시지)
• Help.Link(메시지)
• LocalizedMessage(메시지)
• PreconditionFailure(메시지)
• PreconditionFailure.Violation(메시지)
• QuotaFailure(메시지)
• QuotaFailure.Violation(메시지)
• RequestInfo(메시지)
• ResourceInfo(메시지)
• RetryInfo(메시지)
• Status(메시지)

BadRequest

클라이언트 요청의 위반사항을 설명합니다. 이 오류 유형은 요청의 구문 측면에 중점을 둡니다.

필드
field_violations[]	FieldViolation 클라이언트 요청의 모든 위반사항을 설명합니다.

FieldViolation

단일 잘못된 요청 필드를 설명하는 데 사용되는 메시지 유형입니다.

필드
field	string 요청 본문의 필드로 연결되는 경로입니다. 값은 프로토콜 버퍼 필드를 식별하는 점으로 구분된 식별자 시퀀스입니다. 한 가지 예를 살펴보겠습니다. message CreateContactRequest { message EmailAddress { enum Type { TYPE_UNSPECIFIED = 0; HOME = 1; WORK = 2; } optional string email = 1; repeated EmailType type = 2; } string full_name = 1; repeated EmailAddress email_addresses = 2; } 이 예에서 프로토콜 field는 다음 값 중 하나를 사용할 수 있습니다. full_name 값 위반의 경우 full_name 첫 번째 email_addresses 메시지의 email 필드 위반에 대한 email_addresses[1].email 세 번째 email_addresses 메시지의 두 번째 type 값에 대한 위반의 경우 email_addresses[3].type[2] JSON에서 동일한 값은 다음과 같이 표현됩니다. fullName 값 위반의 경우 fullName 첫 번째 emailAddresses 메시지의 email 필드 위반에 대한 emailAddresses[1].email 세 번째 emailAddresses 메시지의 두 번째 type 값에 대한 위반의 경우 emailAddresses[3].type[2]
description	string 요청 요소가 잘못된 이유에 대한 설명입니다.
reason	string 필드 수준 오류의 이유입니다. 필드 수준 오류의 근본 원인을 식별하는 상수 값입니다. google.rpc.ErrorInfo.domain 범위 내에서 FieldViolation의 유형을 고유하게 식별해야 합니다. 최대 63자(영문 기준)여야 하며 UPPER_SNAKE_CASE를 나타내는 정규 표현식 [A-Z][A-Z0-9_]+[A-Z0-9]와 일치해야 합니다.
localized_message	LocalizedMessage API 소비자에게 반환해도 안전한 필드 수준 오류의 현지화된 오류 메시지를 제공합니다.

코드

gRPC API의 표준 오류 코드입니다.

여러 오류 코드가 적용될 수 있는 경우도 있습니다. 서비스는 적용되는 오류 코드 중 가장 구체적인 코드를 반환해야 합니다. 예를 들어 두 코드가 모두 적용되는 경우 FAILED_PRECONDITION보다는 OUT_OF_RANGE를 사용하세요. 마찬가지로 FAILED_PRECONDITION보다는 NOT_FOUND 또는 ALREADY_EXISTS를 사용해야 합니다.

열거형
OK	오류 아님, 성공 시 반환 HTTP 매핑: 200 OK
CANCELLED	작업이 취소되었습니다. 대개 호출자에 의해 취소됩니다. HTTP 매핑: 499 클라이언트에서 닫은 요청
UNKNOWN	알 수 없는 오류입니다. 예를 들어 다른 주소 공간에서 수신한 Status 값이 이 주소 공간에서 알려지지 않은 오류 공간에 속하는 경우 이 오류가 반환될 수 있습니다. 오류 정보를 충분히 반환하지 않는 API에서 발생한 오류가 이 오류로 변환될 수도 있습니다. HTTP 매핑: 500 내부 서버 오류
INVALID_ARGUMENT	클라이언트에서 잘못된 인수를 지정했습니다. 이는 FAILED_PRECONDITION과 다릅니다. INVALID_ARGUMENT는 시스템 상태에 관계없이 문제가 있는 인수를 나타냅니다(예: 잘못된 형식의 파일 이름). HTTP 매핑: 400 잘못된 요청
DEADLINE_EXCEEDED	작업을 완료하기 전에 기한이 지났습니다. 작업에서 시스템의 상태를 변경하는 경우 작업이 정상적으로 완료되었어도 이 오류가 반환될 수 있습니다. 예를 들어 서버의 성공 응답이 오래 지연되어 기한이 지났을 수 있습니다. HTTP 매핑: 504 게이트웨이 시간 초과
NOT_FOUND	요청한 일부 항목(예: 파일 또는 디렉터리)을 찾을 수 없습니다. 서버 개발자 참고사항: 단계적 기능 출시, 잠정적 허용 목록 등으로 인해 전체 사용자 클래스에게 요청이 거부된 경우에는 NOT_FOUND를 사용할 수 있습니다. 사용자별 액세스 제어 등으로 인해 사용자 클래스에 속하는 일부 사용자에게 요청이 거부된 경우에는 PERMISSION_DENIED를 사용해야 합니다. HTTP 매핑: 404 찾을 수 없음
ALREADY_EXISTS	클라이언트에서 만들려고 시도한 항목(예: 파일 또는 디렉터리)이 이미 존재합니다. HTTP 매핑: 409 충돌
PERMISSION_DENIED	호출자에 지정한 작업을 실행할 권한이 없습니다. 일부 리소스가 소진되었기 때문에 거부된 경우에는 PERMISSION_DENIED가 아닌 RESOURCE_EXHAUSTED를 사용해야 합니다. 호출자를 식별할 수 없는 경우에는 PERMISSION_DENIED가 아닌 UNAUTHENTICATED를 사용해야 합니다. 이 오류 코드는 요청이 유효하다거나, 요청된 항목이 존재한다거나, 다른 전제조건이 충족되었음을 의미하지 않습니다. HTTP 매핑: 403 금지됨
UNAUTHENTICATED	요청에 작업과 관련된 올바른 사용자 인증 정보가 없습니다. HTTP 매핑: 401 승인되지 않음
RESOURCE_EXHAUSTED	일부 리소스가 소진되었습니다. 사용자당 할당량이나 전체 파일 시스템의 저장용량이 부족하기 때문일 수 있습니다. HTTP 매핑: 429 요청한 횟수가 너무 많음
FAILED_PRECONDITION	시스템이 작업 실행에 필요한 상태가 아니기 때문에 작업이 거부되었습니다. 예를 들어 삭제할 디렉터리가 비어 있지 않거나, 디렉터리가 아닌 항목에 rmdir 작업을 적용한 경우입니다. 서비스 구현 시 다음과 같은 가이드라인에 따라 FAILED_PRECONDITION, ABORTED, UNAVAILABLE 중에서 결정할 수 있습니다. (a) 클라이언트에서 실패한 호출만 재시도할 수 있는 경우 UNAVAILABLE을 사용합니다. (b) 클라이언트가 상위 수준에서 다시 시도해야 하는 경우 ABORTED를 사용합니다. 예를 들어 클라이언트에서 지정한 테스트 후 설정 작업이 실패하여 클라이언트가 읽기-수정-쓰기 시퀀스를 다시 시작해야 하는 경우입니다. (c) 시스템 상태가 명시적으로 수정될 때까지 클라이언트에서 재시도하지 말아야 하는 경우 FAILED_PRECONDITION을 사용합니다. 예를 들어 디렉터리가 비어 있지 않아서 'rmdir'이 실패한 경우, 디렉터리에서 파일이 삭제될 때까지 클라이언트에서 재시도하지 말아야 하므로 FAILED_PRECONDITION을 반환해야 합니다. HTTP 매핑: 400 잘못된 요청
ABORTED	작업이 취소되었습니다. 대개 시퀀서 확인 실패, 트랜잭션 취소 등의 동시 실행 문제가 원인입니다. FAILED_PRECONDITION, ABORTED, UNAVAILABLE 중에서 결정하는 방법은 위 가이드라인을 참조하세요. HTTP 매핑: 409 충돌
OUT_OF_RANGE	유효한 범위를 벗어나는 작업을 시도했습니다. 예를 들어 파일 끝을 지나서 탐색하거나 읽으려고 했습니다. INVALID_ARGUMENT와 달리, 이 오류는 시스템 상태가 변경되면 문제가 해결될 수 있음을 나타냅니다. 예를 들어 32비트 파일 시스템에서 [0,2^32-1] 범위를 벗어나는 오프셋으로 읽으려고 하면 INVALID_ARGUMENT가 발생하지만, 현재 파일 크기를 넘어서는 오프셋으로 읽으려고 하면 OUT_OF_RANGE가 발생합니다. FAILED_PRECONDITION과 OUT_OF_RANGE는 다소 겹치는 부분이 있지만, 해당하는 상황이라면 더 구체적인 OUT_OF_RANGE를 사용하는 것이 좋습니다. 그 이유는 특정 공간에서 반복 실행하는 호출자가 간단히 OUT_OF_RANGE 오류를 조회하여 작업이 끝났음을 감지할 수 있기 때문입니다. HTTP 매핑: 400 잘못된 요청
UNIMPLEMENTED	작업이 구현되지 않았거나 이 서비스에서 지원되지 않거나 사용 설정되지 않았습니다. HTTP 매핑: 501 구현되지 않음
INTERNAL	내부 오류가 발생했습니다. 내부 시스템에서 예상하는 불변 항목에 문제가 있는 경우입니다. 이 오류 코드는 심각한 오류를 위해 예약되어 있습니다. HTTP 매핑: 500 내부 서버 오류
UNAVAILABLE	현재 서비스를 사용할 수 없습니다. 일시적인 상태일 가능성이 높으며, 잠시 시간을 두고 다시 시도하면 해결될 수 있습니다. 멱등성이 없는 작업을 재시도하는 것이 항상 안전한 것은 아닙니다. FAILED_PRECONDITION, ABORTED, UNAVAILABLE 중에서 결정하는 방법은 위 가이드라인을 참조하세요. HTTP 매핑: 503 사용할 수 없는 서비스
DATA_LOSS	복구할 수 없는 데이터 손실이나 손상이 발생했습니다. HTTP 매핑: 500 내부 서버 오류

ErrorInfo

구조화된 세부정보를 사용하여 오류의 원인을 설명합니다.

사용 설정되지 않은 'pubsub.googleapis.com' API에 연결할 때 발생하는 오류의 예:

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

이 응답은 pubsub.googleapis.com API가 사용 설정되지 않았음을 나타냅니다.

리소스 소진된 리전에서 Spanner 인스턴스를 만들려고 할 때 반환되는 오류의 예:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}

필드
reason	string 오류의 이유입니다. 오류의 근본 원인을 식별하는 상수 값입니다. 오류 이유는 특정 오류 도메인 내에서 고유합니다. 최대 63자(영문 기준)여야 하며 UPPER_SNAKE_CASE를 나타내는 정규 표현식 [A-Z][A-Z0-9_]+[A-Z0-9]와 일치해야 합니다.
domain	string '이유'가 속한 논리적 그룹입니다. 오류 도메인은 일반적으로 오류를 생성하는 도구 또는 제품의 등록된 서비스 이름입니다. 예: 'pubsub.googleapis.com' 오류가 일부 공통 인프라에 의해 생성된 경우 오류 도메인은 인프라를 식별하는 전역적으로 고유한 값이어야 합니다. Google API 인프라의 경우 오류 도메인은 'googleapis.com'입니다.
metadata	map<string, string> 이 오류에 관한 추가 구조화된 세부정보입니다. 키는 [a-z][a-zA-Z0-9-_]+ 정규 표현식과 일치해야 하지만 lowerCamelCase가 이상적입니다. 또한 길이는 64자로 제한되어야 합니다. 초과된 한도의 현재 값을 식별할 때는 단위가 값에 포함되지 않고 키에 포함되어야 합니다. 예를 들어 클라이언트가 단일 (일괄) 요청에서 생성할 수 있는 인스턴스 수를 초과하는 경우 {"instanceLimit": "100/request"} 대신 {"instanceLimitPerRequest": "100"}이 반환되어야 합니다.

도움말

문서 또는 대역 외 작업을 실행하기 위한 링크를 제공합니다.

예를 들어 호출 프로젝트에서 액세스한 서비스를 사용 설정하지 않았음을 나타내는 오류로 할당량 확인이 실패한 경우 개발자 콘솔에서 비트를 전환할 올바른 위치를 직접 가리키는 URL이 포함될 수 있습니다.

필드
links[]	Link 현재 오류 처리에 관한 추가 정보를 가리키는 URL입니다.

링크

URL 링크를 설명합니다.

필드
description	string 링크에서 제공하는 내용을 설명합니다.
url	string 링크의 URL입니다.

LocalizedMessage

RPC 오류에 연결할 수 있는 사용자에게 반환해도 안전한 현지화된 오류 메시지를 제공합니다.

필드
locale	string https://www.rfc-editor.org/rfc/bcp/bcp47.txt에 정의된 사양에 따라 사용되는 언어입니다. 예: 'en-US', 'fr-CH', 'es-MX'
message	string 위 언어로 된 현지화된 오류 메시지입니다.

PreconditionFailure

실패한 전제 조건을 설명합니다.

예를 들어 서비스 약관을 확인해야 해서 RPC가 실패한 경우 PreconditionFailure 메시지에 서비스 약관 위반이 나열될 수 있습니다.

필드
violations[]	Violation 모든 사전 조건 위반을 설명합니다.

위반

단일 전제 조건 실패를 설명하는 데 사용되는 메시지 유형입니다.

필드
type	string PreconditionFailure의 유형입니다. 지원되는 사전 조건 위반 주체를 정의하려면 서비스별 enum 유형을 사용하는 것이 좋습니다. 예를 들어 '서비스 약관 위반'의 경우 'TOS'입니다.
subject	string 실패한 유형과 관련된 주제입니다. 예를 들어 'TOS' 유형과 관련된 'google.com/cloud'는 참조되는 서비스 약관을 나타냅니다.
description	string 전제 조건이 실패한 방식에 대한 설명입니다. 개발자는 이 설명을 사용하여 실패를 수정하는 방법을 이해할 수 있습니다. 예: '서비스 약관에 동의하지 않음'

QuotaFailure

할당량 검사가 실패한 방법을 설명합니다.

예를 들어 호출 프로젝트의 일일 한도가 초과된 경우 서비스는 프로젝트 ID와 초과된 할당량 한도의 설명을 포함하는 QuotaFailure 세부정보로 응답할 수 있습니다. 호출 프로젝트에서 개발자 콘솔의 서비스를 사용 설정하지 않은 경우 서비스는 프로젝트 ID로 응답하고 service_disabled를 true로 설정할 수 있습니다.

할당량 실패 처리에 관한 기타 세부정보는 RetryInfo 및 Help 유형을 참고하세요.

필드
violations[]	Violation 모든 할당량 위반을 설명합니다.

위반

단일 할당량 위반을 설명하는 데 사용되는 메시지 유형입니다. 예를 들어 일일 할당량 또는 맞춤 할당량이 초과되었습니다.

필드
subject	string 할당량 확인에 실패한 주체입니다. 예를 들어 'clientip:' 또는 'project:'입니다.
description	string 할당량 검사가 실패한 방식에 대한 설명입니다. 클라이언트는 이 설명을 사용하여 서비스의 공개 문서에서 할당량 구성에 대해 자세히 알아보거나 개발자 콘솔을 통해 조정할 관련 할당량 한도를 찾을 수 있습니다. 예: '서비스 사용 중지됨' 또는 '읽기 작업의 일일 한도 초과'
api_service	string QuotaFailure.Violation가 시작되는 API 서비스입니다. 경우에 따라 할당량 문제는 호출된 API 서비스가 아닌 다른 API 서비스에서 발생합니다. 즉, 호출된 API 서비스의 종속 항목이 QuotaFailure의 원인일 수 있으며 이 필드에는 종속 항목 API 서비스 이름이 표시됩니다. 예를 들어 호출된 API가 Kubernetes Engine API (container.googleapis.com)이고 Kubernetes Engine API 자체에서 할당량 위반이 발생한 경우 이 필드는 'container.googleapis.com'이 됩니다. 반면 Kubernetes Engine API가 Compute Engine API (compute.googleapis.com)에서 VM을 만들 때 할당량 위반이 발생하면 이 필드는 'compute.googleapis.com'이 됩니다.
quota_metric	string 위반된 할당량의 측정항목입니다. 할당량 측정항목은 API 요청 또는 CPU와 같은 사용량을 측정하는 명명된 카운터입니다. 가상 머신 할당과 같은 서비스에서 활동이 발생하면 하나 이상의 할당량 측정항목이 영향을 받을 수 있습니다. 예: 'compute.googleapis.com/cpus_per_vm_family', 'storage.googleapis.com/internet_egress_bandwidth'
quota_id	string 위반된 할당량의 ID입니다. '한도 이름'이라고도 하며, API 서비스 컨텍스트에서 할당량의 고유 식별자입니다. 예: 'CPUS-PER-VM-FAMILY-per-project-region'
quota_dimensions	map<string, string> 위반된 할당량의 측정기준입니다. 전역이 아닌 모든 할당량은 측정기준 집합에 적용됩니다. 할당량 측정항목은 집계할 항목을 정의하는 반면 측정기준은 카운터를 늘려야 하는 측면을 지정합니다. 예를 들어 'VM 제품군별 리전의 CPU' 할당량은 '리전' 및 'vm_family' 측정기준에 대해 'compute.googleapis.com/cpus_per_vm_family' 측정항목의 한도를 적용합니다. 위반이 'us-central1' 리전에서 'n1' VM 제품군에 대해 발생한 경우 quota_dimensions는 다음과 같습니다. { "region": "us-central1", "vm_family": "n1", } 할당량이 전역적으로 적용되면 quota_dimensions는 항상 비어 있습니다.
quota_value	int64 QuotaFailure 시점의 강제 할당량 값입니다. 예를 들어 CPU 수에 적용된 할당량 값이 QuotaFailure 시점에 '10'이면 이 필드의 값은 이 수량을 반영합니다.
future_quota_value	int64 위반 시점에 출시되는 새 할당량 값입니다. 출시가 완료되면 이 값이 quota_value 대신 적용됩니다. 위반 시점에 진행 중인 출시가 없으면 이 필드는 설정되지 않습니다. 예를 들어 위반 시점에 CPU 할당량을 10에서 20으로 변경하는 출시가 진행 중인 경우 이 필드의 값은 20이 됩니다.

RequestInfo

클라이언트가 버그를 신고하거나 다른 형태의 의견을 제공할 때 첨부할 수 있는 요청에 관한 메타데이터를 포함합니다.

필드
request_id	string 생성하는 서비스에서만 해석해야 하는 불투명 문자열입니다. 예를 들어 서비스 로그에서 요청을 식별하는 데 사용할 수 있습니다.
serving_data	string 이 요청을 처리하는 데 사용된 데이터입니다. 예를 들어 디버깅을 위해 서비스 제공업체에 다시 전송할 수 있는 암호화된 스택 트레이스입니다.

ResourceInfo

액세스 중인 리소스를 설명합니다.

필드
resource_type	string 액세스하는 리소스 유형의 이름입니다(예: 'SQL 테이블', '클라우드 스토리지 버킷', '파일', 'Google Calendar'). 또는 리소스의 유형 URL입니다(예: 'type.googleapis.com/google.pubsub.v1.Topic').
resource_name	string 액세스 중인 리소스의 이름입니다. 예를 들어 현재 오류가 google.rpc.Code.PERMISSION_DENIED인 경우 공유 캘린더 이름은 '[e-mail]'입니다.
owner	string 리소스의 소유자 (선택사항) 예를 들어 'user:' 또는 'project:'입니다.
description	string 이 리소스에 액세스할 때 발생한 오류를 설명합니다. 예를 들어 클라우드 프로젝트를 업데이트하려면 개발자 콘솔 프로젝트에 대한 writer 권한이 필요할 수 있습니다.

RetryInfo

클라이언트가 실패한 요청을 재시도할 수 있는 시점을 설명합니다. 클라이언트는 여기에서 추천을 무시하거나 오류 응답에서 이 정보가 누락된 경우 재시도할 수 있습니다.

클라이언트는 재시도할 때 항상 지수 백오프를 사용하는 것이 좋습니다.

클라이언트는 오류 응답을 수신한 후 retry_delay 시간이 지날 때까지 기다린 후 재시도해야 합니다. 요청 재시도도 실패하는 경우 클라이언트는 최대 재시도 횟수에 도달하거나 최대 재시도 지연 시간 상한에 도달할 때까지 retry_delay에 따라 재시도 간 지연 시간을 점진적으로 늘리는 지수 백오프 체계를 사용해야 합니다.

필드
retry_delay	Duration 클라이언트는 동일한 요청을 재시도할 때 최소한 이 시간만큼 기다려야 합니다.

상태

Status 유형은 REST API, RPC API를 비롯하여 다양한 프로그래밍 환경에 적합한 논리적 오류 모델을 정의하며, gRPC에서 사용됩니다. 각 Status 메시지에는 오류 코드, 오류 메시지, 오류 세부정보라는 3가지 데이터가 포함됩니다.

API 설계 가이드에서 이 오류 모델과 모델 작업 방법에 대해 자세히 알아볼 수 있습니다.

필드
code	int32 상태 코드로, google.rpc.Code의 열거형 값이어야 합니다.
message	string 개발자에게 정보를 제공하는 오류 메시지로, 영어로 작성되어야 합니다. 사용자에게 표시되는 모든 오류 메시지는 현지화되어 google.rpc.Status.details 필드에 전송되거나, 클라이언트 측에서 현지화되어야 합니다.
details[]	Any 오류 세부정보를 설명하는 메시지 목록입니다. API에서 사용할 일반적인 메시지 유형 집합이 있습니다.