---
title: Google AIP-193 — Errors (google.rpc.Status)
source_type: official-doc
url: https://google.aip.dev/193
archive_url:
status: raw
confidence: high
tags: [ca-error-envelope, google, grpc, custom-envelope, rest-api, error-format, aip, official-doc]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-operational-error-observability-foundation, feature-boundary-validation-mapping-contract, feature-business-rule-validation-contract]
created: 2026-05-22
last_reviewed: 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 매핑, 해석):
  ```json
  {
    "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 / 관련

- 같은 주제 다른 official-doc / company-tech-blog:
  - [[raw/official-docs/spring-problem-detail]] (대안 1 구현체 — RFC 7807/9457)
  - [[raw/official-docs/json-api-errors-spec]] (대안 3 — JSON:API errors)
  - [[raw/official-docs/graphql-errors-spec]] (대안 4 — GraphQL errors)
  - [[raw/company-tech-blogs/stripe-error-format]] (대안 5 — Stripe custom envelope)
- canonical contract 섹션:
  - [[raw/project-notes/ca-skeleton-operational-contract]] §3 Structured API Response Contract, §6 Operational Error Category
- 본 source 의 위치: ca-tmpl Topic 4 — Error Envelope, **대안 2: Google rpc.Status (gRPC-derived)**
- 인용하는 wiki: (미작성)