donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/raw/official-docs/google-api-error-format.md
T

9.3 KiB
Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
title source_type url archive_url status confidence tags related_projects related_branches created last_reviewed
Google AIP-193 — Errors (google.rpc.Status) official-doc https://google.aip.dev/193 raw high
ca-error-envelope
google
grpc
custom-envelope
rest-api
error-format
aip
official-doc
ca-skeleton-operational-contract
feature-operational-error-observability-foundation
feature-boundary-validation-mapping-contract
feature-business-rule-validation-contract
2026-05-22 2026-05-27

Google AIP-193 — Errors (google.rpc.Status)

Layer: raw/official-docs/ — Google API Improvement Proposal 193 (Errors). REST 와 gRPC 양쪽에 동일 모델 매핑되는 typed error 표준의 1차 근거. ca-tmpl Topic 4 (Error Envelope) 의 대안 2 (Google rpc.Status / gRPC-derived) 비교 근거.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-operational-error-observability-foundation ca-tmpl Topic 4 (Error Envelope) 대안 비교 — details: Any[] 다형성 + typed ErrorInfo/RetryInfo/LocalizedMessage 의 표준 근거
raw/branch-notes/feature-boundary-validation-mapping-contract boundary 입력 검증 실패 시 BadRequest typed detail 옵션의 표준 근거
raw/branch-notes/feature-business-rule-validation-contract business rule 실패의 ErrorInfo.reason + domain 기반 머신리더블 식별자 패턴 — RFC 7807 type URI 와의 비교

컨텍스트 / 왜 저장했는지

가장 정교한 typed error model. details array 가 Any 패킹으로 다형성을 가지며, 그 안에 ErrorInfo / LocalizedMessage / Help / RetryInfo / QuotaFailure / BadRequest 등이 들어감 → ca-tmpl 의 details: object 와 비교했을 때 표현력 trade-off 가 명확해짐. gRPC 생태계 (grpc-gateway, gapic generator) 의 사실상 표준.

출처 / Source

  • 원본 URL: https://google.aip.dev/193
  • 기반: google.rpc.Status (protobuf), google.rpc.Code enum
  • 아카이브 URL: (미수집)
  • 저자 / 조직: Google (AIP Working Group)
  • 발행일: rolling (AIP-193, current)
  • 마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Status.code] "The code field is the status code, which must be the numeric value of one of the elements of the google.rpc.Code enum."

[§Status.message] "The message field is a developer-facing, human-readable "debug message" which should be in English."

[§Status.details] "The details field allows messages with additional error information to be included in the error response, each packed in a google.protobuf.Any message."

[§Status.details — ErrorInfo requirement] "All error responses must include an ErrorInfo within details."

[§Status.details — standard payloads] "BadRequest", "PreconditionFailure", "ErrorInfo", "LocalizedMessage", "Help" — 표준 detail payload 로 명시 (RetryInfo, QuotaFailure 등 추가 표준 payload 는 별도 error_details.proto 정의)

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
GOOG-ERR-C1 code 필드는 google.rpc.Code enum 의 정수 값 이어야 함 (must) [§Status.code] "The code field is the status code, which must be the numeric value of one of the elements of the google.rpc.Code enum." official-vendor-doc Google API / gRPC Status 호환 응답 HTTP status code 와 1:1 매핑이라는 뜻은 아님 — google.rpc.Code 는 별도 enum (NOT_FOUND=5 등)
GOOG-ERR-C2 message 필드는 개발자 대상의 영어 debug message (should) — end-user 표시용 아님 [§Status.message] "The message field is a developer-facing, human-readable "debug message" which should be in English." official-vendor-doc API 응답의 message 필드 표시 정책 end-user 메시지가 별도 LocalizedMessage 로 강제된다는 뜻은 아님 — 본 인용은 message 자체의 의도만 정의
GOOG-ERR-C3 details 필드는 google.protobuf.Any 로 패킹된 추가 정보를 array 로 포함 (다형성) [§Status.details] "The details field allows messages with additional error information to be included in the error response, each packed in a google.protobuf.Any message." official-vendor-doc typed error details 표현 client 가 Any 디코딩 비용 없이 처리 가능하다는 뜻은 아님 — @type URL 기반 해석 필요
GOOG-ERR-C4 모든 error 응답 은 details 안에 ErrorInfo 를 반드시 포함 해야 함 (must) [§Status.details — ErrorInfo requirement] "All error responses must include an ErrorInfo within details." official-vendor-doc AIP-193 준수 API 의 모든 error 응답 ErrorInfo.reason 값 카탈로그가 spec 에 고정되어 있다는 뜻은 아님 — domain 별 자유 정의
GOOG-ERR-C5 표준 detail payload 로 BadRequest, PreconditionFailure, ErrorInfo, LocalizedMessage, Help 등이 정의됨 [§Status.details — standard payloads] "BadRequest", "PreconditionFailure", "ErrorInfo", "LocalizedMessage", "Help" official-vendor-doc typed details 카탈로그 사용 RetryInfo / QuotaFailure 가 본 AIP-193 페이지에 직접 인용되었다는 뜻은 아님 — error_details.proto 의 추가 payload (별도 확인)

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • GOOG-ERR-C1: code 가 google.rpc.Code enum 정수임 (HTTP status code 와 별개)
    • GOOG-ERR-C2: message 의 developer-facing English 의도
    • GOOG-ERR-C3: details: Any[] 다형성 구조
    • GOOG-ERR-C4: 모든 error 응답에 ErrorInfo 필수
    • GOOG-ERR-C5: 표준 detail payload 5종 (BadRequest, PreconditionFailure, ErrorInfo, LocalizedMessage, Help) 의 존재
  • 이 자료가 증명하지 않는 것:
    • RetryInfo.retry_delay 가 client 의 표준 재시도 정책으로 강제됨 (별도 error_details.proto 참조 필요)
    • REST mapping 의 정확한 JSON shape (error.code 가 정수 vs 문자열 enum name 인지 — AIP-193 본문은 다른 § 에서 정의)
    • HTTP status code 와 google.rpc.Code 간 매핑 표 (별도 AIP — AIP-194 또는 grpc-status-codes-to-http 표)
    • @type 의 정확한 URL prefix 정책 (type.googleapis.com 외 cusotm prefix 허용 여부)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • ca-tmpl 의 retryable: boolean 을 RetryInfo.retry_delay 로 대체 시 client SDK 영향
    • details 다형성 채택 시 client 가 알아야 할 @type 카탈로그의 운영 비용
    • LocalizedMessage 채택 시 i18n 파이프라인 (message vs LocalizedMessage.message 분리) 의 구현 비용

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

  • 응답 shape 예시 (REST 매핑, 해석): 
    {
  "error": {
    "code": 404,
    "message": "Resource 'projects/foo' not found.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_NOT_FOUND",
        "domain": "googleapis.com",
        "metadata": {"resource": "projects/foo"}
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "ko-KR",
        "message": "..."
      }
    ]
  }
}
  • 장점 (해석):
    • typed details — RetryInfo 로 retryable + delay 까지 표준화, ca-tmpl 의 retryable boolean 보다 풍부
    • LocalizedMessage 로 i18n 이 spec 수준에서 정의됨
    • REST/gRPC 일관 — bilingual API 에 유리
    • ErrorInfo.reason + domain 이 RFC 7807 의 type URI 역할
  • 단점 (해석):
    • 복잡도가 매우 높음. Any 디코딩이 client 에 부담
    • 가벼운 CRUD API 에는 과함
    • 표준 detail 타입 카탈로그를 알아야 효용 발휘
  • ca-tmpl custom envelope 와의 차이 (해석):
    • ca-tmpl: retryable: boolean, Google: RetryInfo { retry_delay }. 후자가 client 에 더 actionable
    • ca-tmpl: 단일 details: object, Google: details: Any[] 다형성
    • ca-tmpl: category: string, Google: 정수 code + 문자열 status enum
  • 표준 준수 / lock-in / client 호환성 (해석):
    • Google 진영의 사실상 표준. 외부 표준은 아니지만 gRPC 생태계 전체가 따라감 → grpc-gateway, gapic generator 등
    • lock-in: protobuf/grpc 생태계와 강결합
  • localization / i18n 지원 여부 (해석):
    • LocalizedMessage detail 로 1급 지원. 5개 대안 중 가장 명시적

Related / 관련

Reference in New Issue View Git Blame Copy Permalink