7.2 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| gRPC status codes / Connect protocol — 오류 표현 방식 | official-doc | https://github.com/grpc/grpc/blob/master/doc/statuscodes.md |
|
|
|
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
statusobject composed of an integercodeand a stringmessage" 를 반환한다.
[§Connect — Error and EndStreamResponse] "An
Erroris a code, an optional message, and an optional array of details."
[§Connect — Error and EndStreamResponse] "The simplest form of
Errorcontains 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 코드 → 우리 error kind 매핑표의 구체 내용 —
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- gRPC-Web 규격 원문 (trailer 인코딩과
grpc-status헤더 위치) - Connect 의 code 문자열 ↔ gRPC 숫자 code 대응표
- gRPC-Web 규격 원문 (trailer 인코딩과
메모
- 인용 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 요약: 생성 전