liminfogRPC Status Code Reference
gRPC/HTTP 상태 코드 매핑 레퍼런스
| gRPC | 코드 | HTTP | 유형 | 설명 | 예시 |
|---|---|---|---|---|---|
OK | 0 | 200 | 성공 | 성공 | |
CANCELLED | 1 | 499 | 클라이언트 | 클라이언트가 요청 취소 | |
UNKNOWN | 2 | 500 | 서버 | 알 수 없는 오류 | |
INVALID_ARGUMENT | 3 | 400 | 클라이언트 | 잘못된 요청 인자 | |
DEADLINE_EXCEEDED | 4 | 504 | 서버 | 데드라인 초과 | |
NOT_FOUND | 5 | 404 | 클라이언트 | 리소스를 찾을 수 없음 | |
ALREADY_EXISTS | 6 | 409 | 클라이언트 | 리소스가 이미 존재 | |
PERMISSION_DENIED | 7 | 403 | 클라이언트 | 권한 거부 | |
RESOURCE_EXHAUSTED | 8 | 429 | 서버 | 리소스 소진 (요청 제한) | |
FAILED_PRECONDITION | 9 | 400 | 클라이언트 | 사전 조건 실패 | |
ABORTED | 10 | 409 | 서버 | 작업 중단 (트랜잭션 충돌) | |
OUT_OF_RANGE | 11 | 400 | 클라이언트 | 범위 초과 | |
UNIMPLEMENTED | 12 | 501 | 서버 | 구현되지 않은 메서드 | |
INTERNAL | 13 | 500 | 서버 | 내부 오류 | |
UNAVAILABLE | 14 | 503 | 서버 | 서비스 사용 불가 | |
DATA_LOSS | 15 | 500 | 서버 | 데이터 손실 | |
UNAUTHENTICATED | 16 | 401 | 클라이언트 | 인증 필요 |
gRPC Status Code Reference 소개
gRPC 상태 코드 레퍼런스는 Google이 정의한 17개 공식 gRPC 상태 코드의 완전한 검색 가능 매핑을 제공합니다. 각 코드의 문자열 이름(예: NOT_FOUND), 숫자 코드(0~16), 대응하는 HTTP 상태 코드, 간결한 설명을 확인할 수 있습니다. 개발자는 검색 필드에 gRPC 상태 이름, 숫자 코드, HTTP 코드를 입력해 실시간으로 테이블을 필터링할 수 있어 디버깅이나 API 설계 중 빠른 조회가 가능합니다.
gRPC는 HTTP와 별도의 상태 코드 체계를 사용하며, 둘 사이의 매핑은 REST-gRPC 트랜스코딩 레이어, API 게이트웨이, 오류 처리 미들웨어를 구축할 때 자주 필요합니다. 예를 들어 gRPC OK(코드 0)는 HTTP 200, NOT_FOUND(코드 5)는 HTTP 404, PERMISSION_DENIED(코드 7)는 HTTP 403, UNAVAILABLE(코드 14)는 HTTP 503에 매핑됩니다. 표시된 HTTP 매핑은 Google의 gRPC HTTP/JSON 트랜스코딩 명세에서 권장하는 정식 매핑을 따릅니다.
이 레퍼런스는 gRPC 서비스를 구축하는 백엔드 개발자, DevOps 엔지니어, 오류 처리 규약을 설계하는 API 아키텍트를 위해 설계되었습니다. 테이블은 서버 요청 없이 브라우저에서 완전히 렌더링되며, HTTP 상태 코드는 색상으로 구분됩니다. 2xx 성공 코드는 녹색, 4xx 클라이언트 오류는 노란색, 5xx 서버 오류는 빨간색으로 표시되어 각 gRPC 오류의 심각도를 시각적으로 파악할 수 있습니다.
주요 기능
- OK(0)부터 UNAUTHENTICATED(16)까지 17개 공식 gRPC 상태 코드 전체 포함
- gRPC 이름, 숫자 코드, HTTP 상태 코드로 실시간 검색
- HTTP 배지 색상 구분: 녹색(2xx), 노란색(4xx), 빨간색(5xx)
- gRPC 문자열 이름과 숫자 코드 나란히 표시
- Google gRPC 트랜스코딩 명세에 따른 정식 HTTP 매핑
- 검색이 올바르게 작동함을 확인하는 결과 수 표시
- 영어·한국어 이중 언어 설명 지원
- 100% 클라이언트 사이드 — 페이지 로드 후 네트워크 요청 없음
자주 묻는 질문
gRPC의 17개 상태 코드는 무엇인가요?
gRPC는 17개의 상태 코드를 정의합니다: 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). 각 코드는 트랜스코딩을 위한 HTTP 매핑이 정의되어 있습니다.
gRPC에서 PERMISSION_DENIED와 UNAUTHENTICATED의 차이는 무엇인가요?
UNAUTHENTICATED(코드 16, HTTP 401)는 클라이언트가 인증 자격증명을 제공하지 않았거나 자격증명이 유효하지 않음을 의미합니다. PERMISSION_DENIED(코드 7, HTTP 403)는 클라이언트가 인증되었지만 요청한 작업을 수행할 권한이 없음을 의미합니다. 간단히 말해 UNAUTHENTICATED는 "당신이 누구인지 모릅니다"이고, PERMISSION_DENIED는 "당신이 누구인지 알지만 이 작업은 허용되지 않습니다"입니다.
gRPC CANCELLED가 HTTP 499에 매핑되는 이유는 무엇인가요?
HTTP 499는 Nginx가 서버가 응답하기 전에 클라이언트가 연결을 닫았음을 나타내기 위해 사용하는 비표준 코드입니다. gRPC CANCELLED 상태(코드 1)는 클라이언트가 진행 중인 RPC를 취소했음을 의미하며, 이는 클라이언트가 연결을 끊는 것과 개념적으로 유사합니다. Google은 CANCELLED의 정식 트랜스코딩 매핑으로 HTTP 499를 채택했습니다.
gRPC RESOURCE_EXHAUSTED는 언제 반환해야 하나요?
RESOURCE_EXHAUSTED(코드 8, HTTP 429)는 리소스가 소진되었음을 나타내며, 가장 일반적으로 요청 속도 제한이나 할당량 초과 시 사용됩니다. 클라이언트가 허용된 요청 속도를 초과하거나, 서버 리소스 풀이 가득 찼거나, 할당량에 도달했을 때 반환합니다. 클라이언트는 이 상태를 받으면 지수 백오프로 재시도해야 합니다.
FAILED_PRECONDITION, ABORTED, UNAVAILABLE의 차이는 무엇인가요?
FAILED_PRECONDITION(코드 9)은 시스템이 해당 작업을 실행하기 위한 필수 상태가 아님을 의미합니다(예: 비어 있지 않은 디렉터리 삭제 시도). ABORTED(코드 10)는 비교-교체 실패나 트랜잭션 중단과 같은 동시성 충돌로 작업이 중단되었음을 나타냅니다. UNAVAILABLE(코드 14)은 서비스가 일시적으로 사용 불가능하며 재시도 가능함을 의미합니다. FAILED_PRECONDITION과 ABORTED는 일반적으로 사전 조건을 수정하지 않으면 재시도할 수 없지만, UNAVAILABLE은 항상 재시도해도 안전합니다.
gRPC DEADLINE_EXCEEDED를 클라이언트에서 어떻게 처리해야 하나요?
DEADLINE_EXCEEDED(코드 4, HTTP 504)는 호출자가 설정한 데드라인 내에 작업이 완료되지 않았음을 의미합니다. CANCELLED와 구별해야 합니다: DEADLINE_EXCEEDED는 데드라인 만료 전 서버가 요청을 처리했는지 여부가 불분명합니다. 읽기 같은 멱등 작업은 새 데드라인으로 재시도해도 안전합니다. 쓰기 같은 비멱등 작업은 중복 실행을 피하기 위해 재시도 전 서버 상태를 확인해야 합니다.
gRPC INTERNAL 상태 코드는 무엇을 의미하나요?
INTERNAL(코드 13, HTTP 500)은 시스템이 기대하는 불변 조건이 깨졌음을 나타냅니다. UNKNOWN(코드 2, HTTP 500)이 진정으로 알 수 없는 오류나 gRPC 상태 코드를 사용하지 않는 하위 시스템의 오류에 사용되는 반면, INTERNAL은 서버가 특정 내부 불일치나 프로그래밍 오류를 감지했을 때 사용됩니다. 클라이언트는 일반적으로 INTERNAL 오류를 조사 없이 재시도하지 않아야 합니다.
gRPC-Gateway나 gRPC-Web 트랜스코딩 레퍼런스로 이 표를 사용할 수 있나요?
네. 이 표에 표시된 HTTP 매핑은 gRPC HTTP/JSON 트랜스코딩 명세와 grpc-gateway 프로젝트의 기본값을 따릅니다. grpc-gateway로 gRPC 서비스를 REST API로 노출하거나 Envoy의 gRPC-JSON 트랜스코딩 필터를 사용할 때 각 gRPC 오류 상태에 대해 기본적으로 반환되는 HTTP 상태 코드가 이 표와 같습니다. 일부 게이트웨이는 프로토 어노테이션으로 특정 매핑을 재정의할 수 있습니다.