92 lines
7.2 KiB
Markdown
92 lines
7.2 KiB
Markdown
---
|
|
title: gRPC status codes / Connect protocol — 오류 표현 방식
|
|
source_type: official-doc
|
|
url: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
|
|
archive_url:
|
|
related_branches: [feature-frontend-multi-protocol-api-transport-contract]
|
|
related_projects: [ca-skeleton-frontend]
|
|
tags: [frontend, grpc, grpc-web, connect, protocol, error-handling]
|
|
created: 2026-07-28
|
|
---
|
|
|
|
# gRPC status codes / Connect protocol — 오류 표현 방식
|
|
|
|
> Layer: `raw/` — 외부 자료의 **원문 발췌·출처 기록**.
|
|
|
|
## 활용 branch (필수, 최소 1개+)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| `[[raw/branch-notes/feature-frontend-multi-protocol-api-transport-contract]]` | protocol 별 성공 판정을 분리하는 근거(`D2`), gRPC-Web 과 Connect 를 한 adapter 로 묶지 못하는 근거(`D7`), 재시도 가능 판정이 규격이 아니라 **우리 결정**이라는 근거(`D6`) |
|
|
|
|
## 출처
|
|
|
|
- 원본 URL: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md
|
|
- 보조 URL: https://connectrpc.com/docs/protocol/
|
|
- 아카이브 URL:
|
|
- 저자 / 조직: gRPC Authors / Connect (Buf)
|
|
- 발행일: (지속 갱신)
|
|
- 마지막 확인일: 2026-07-28
|
|
|
|
## 왜 저장했는지
|
|
|
|
branch 가 `grpc-status` ↔ 정규화 kind 매핑표를 "명세 확인 후" 로 비워 두었다. 확인해 보니 매핑표에 필요한 것은 두 가지였고 성격이 정반대였다. (a) 코드 목록은 규격이 확정해 준다. (b) **어떤 코드가 재시도 가능한지는 규격이 정해 주지 않는다** — 명시적으로 애플리케이션에 떠넘긴다. 그리고 gRPC-Web 과 Connect 는 이름이 비슷한데 오류를 알리는 방식이 정반대여서, 하나의 adapter 로 묶으면 한쪽이 반드시 틀린다.
|
|
|
|
## 핵심 인용
|
|
|
|
> [§gRPC statuscodes — Status code 표] "OK 0 / CANCELLED 1 / UNKNOWN 2 / INVALID_ARGUMENT 3 / DEADLINE_EXCEEDED 4 / NOT_FOUND 5 / ALREADY_EXISTS 6 / PERMISSION_DENIED 7 / RESOURCE_EXHAUSTED 8 / FAILED_PRECONDITION 9 / ABORTED 10 / OUT_OF_RANGE 11 / UNIMPLEMENTED 12 / INTERNAL 13 / UNAVAILABLE 14 / DATA_LOSS 15 / UNAUTHENTICATED 16"
|
|
|
|
> [§gRPC statuscodes] "there is no fixed list of status codes on which it is appropriate to retry in all applications. As a result, individual applications must make their own determination as to which status codes should cause an RPC to be retried."
|
|
|
|
> [§gRPC statuscodes] RPC 는 "a `status` object composed of an integer `code` and a string `message`" 를 반환한다.
|
|
|
|
> [§Connect — Error and EndStreamResponse] "An `Error` is a code, an optional message, and an optional array of details."
|
|
|
|
> [§Connect — Error and EndStreamResponse] "The simplest form of `Error` contains just a code: `{\"code\": \"unavailable\"}`"
|
|
|
|
> [§Connect — Error Codes] "Connect represents categories of errors as codes, and each code maps to a specific HTTP status code."
|
|
|
|
> [§Connect — Unary-Response] "Errors are sent with a non-200 **HTTP-Status**."
|
|
|
|
> [§Connect — Summary] "The protocol doesn't use HTTP trailers at all, so it works with any networking infrastructure."
|
|
|
|
> [§Connect — Streaming-Request] "Note that this is not the same as the gRPC-Web protocol, which uses the _most_ significant bit to mark trailers."
|
|
|
|
## 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| C1 | gRPC status code 는 0(OK)부터 16(UNAUTHENTICATED)까지 17개로 확정되어 있다 | [§표] "OK 0 ... UNAUTHENTICATED 16" | `official-reference` | gRPC 계열 전체 | 각 코드가 어떤 상황에 쓰이는지의 판단 기준 |
|
|
| C2 | **어떤 코드에서 재시도해야 하는지는 규격이 정하지 않으며 애플리케이션이 스스로 정한다** | [§statuscodes] "individual applications must make their own determination as to which status codes should cause an RPC to be retried." | `official-reference` | 재시도 정책 | 우리가 고른 재시도 집합이 옳다는 것 — 규격은 판단을 위임할 뿐이다 |
|
|
| C3 | gRPC 의 status 는 code + message 객체이며 transport 와 **별도로** 전달된다 | [§statuscodes] "a `status` object composed of an integer `code` and a string `message`" | `official-reference` | gRPC·gRPC-Web | HTTP 상태 코드와의 구체적 매핑 |
|
|
| C4 | Connect 의 오류는 `code`(문자열)와 선택적 message·details 로 구성된 JSON 이다 | [§Connect] "An `Error` is a code, an optional message, and an optional array of details." | `official-reference` | Connect unary | 문자열 code 가 gRPC 숫자 code 와 1:1 이라는 것 |
|
|
| C5 | Connect 는 오류를 **non-200 HTTP status 로 보낸다** | [§Unary-Response] "Errors are sent with a non-200 **HTTP-Status**." | `official-reference` | Connect unary | 스트리밍에서도 같다는 것 |
|
|
| C6 | Connect 는 HTTP trailer 를 전혀 쓰지 않는다 | [§Summary] "The protocol doesn't use HTTP trailers at all" | `official-reference` | Connect 전체 | gRPC-Web 도 그렇다는 것 — 오히려 반대다 |
|
|
| C7 | gRPC-Web 은 trailer 를 별도 표시로 구분하며 Connect 와 **다른 프로토콜**이다 | [§Streaming-Request] "this is not the same as the gRPC-Web protocol, which uses the _most_ significant bit to mark trailers." | `official-reference` | 두 프로토콜의 차이 | gRPC-Web 의 trailer 인코딩 세부 |
|
|
| C8 | Connect 는 각 code 를 특정 HTTP status 로 매핑한다 | [§Error Codes] "each code maps to a specific HTTP status code" | `official-reference` | Connect | 그 매핑이 gRPC-Web 에도 적용된다는 것 |
|
|
|
|
## 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `C1`·`C3`: gRPC 코드 집합과 status 가 transport 와 분리되어 있다는 사실
|
|
- `C2`: **재시도 가능 판정은 규격이 위임한 애플리케이션 결정**이다
|
|
- `C4`~`C8`: Connect 와 gRPC-Web 의 오류 표현이 서로 다르다 — Connect 는 non-200 + JSON, gRPC-Web 은 200 + trailer
|
|
- 이 자료가 증명하지 않는 것:
|
|
- gRPC 코드 → 우리 error kind 매핑표의 구체 내용 — `C2` 가 명시적으로 우리에게 넘긴다
|
|
- gRPC-Web 의 trailer 파싱 세부 (별도 gRPC-Web 규격 필요)
|
|
- 어떤 프로토콜을 우리가 실제로 쓸지
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- gRPC-Web 규격 원문 (trailer 인코딩과 `grpc-status` 헤더 위치)
|
|
- Connect 의 code 문자열 ↔ gRPC 숫자 code 대응표
|
|
|
|
## 메모
|
|
|
|
- 인용 1 해석 후보 (미검증): `C5`+`C7` 은 "gRPC 계열" 이라는 묶음이 구현 관점에서 성립하지 않음을 보여준다. gRPC-Web 은 HTTP 200 이어도 실패일 수 있고, Connect 는 실패면 HTTP 가 200 이 아니다. 성공 판정 코드를 공유하면 한쪽이 반드시 틀린다.
|
|
- 인용 2 해석 후보 (미검증): `C2` 때문에 매핑표는 "규격 확인 후 채운다" 가 아니라 **"우리가 정하고 근거를 남긴다"** 가 맞다. 규격을 아무리 읽어도 재시도 여부는 나오지 않는다.
|
|
- 추가로 봐야 할 동일 출처 페이지: gRPC-Web 규격(`PROTOCOL-WEB.md`), Connect 의 code ↔ HTTP status 표 전체
|
|
|
|
## 관련
|
|
|
|
- 같은 주제 다른 official-doc: `[[raw/official-docs/graphql-over-http-draft-status-errors]]`
|
|
- 이 자료를 인용한 wiki 요약: 생성 전
|