gRPC 상태 코드 사전
gRPC 상태 코드(0~16)의 뜻과 언제 나는지 찾아봅니다. HTTP 상태 코드와는 다른 체계입니다.
에러가 아닙니다. 성공적으로 처리됐습니다.
작업이 취소됐습니다. 보통 호출한 쪽이 취소를 요청한 경우입니다.
어느 에러 공간에도 속하지 않는, 원인을 알 수 없는 에러입니다.
클라이언트가 잘못된 인자를 보냈습니다. 시스템 상태와 무관하게 그 자체로 문제가 있는 경우입니다.
작업이 끝나기 전에 정해진 기한(deadline)이 지났습니다.
요청한 대상(파일·디렉터리 등)을 찾을 수 없습니다.
만들려는 대상이 이미 존재합니다.
호출한 쪽에 해당 작업을 실행할 권한이 없습니다.
할당량이나 디스크 공간 같은 자원이 바닥났습니다.
시스템이 이 작업을 실행할 수 있는 상태가 아닙니다.
동시성 문제 등으로 작업이 중단됐습니다.
유효한 범위를 벗어난 지점에서 작업을 시도했습니다.
이 서비스에서 구현돼 있지 않거나 지원·활성화되지 않은 작업입니다.
시스템이 기대하는 불변조건이 깨진, 내부 에러입니다.
서비스가 지금 이용할 수 없습니다. 대부분 일시적이라 재시도(backoff)하면 해결됩니다.
복구할 수 없는 데이터 손실이나 손상이 있었습니다.
요청에 유효한 인증 정보가 없습니다.
사용 방법
- 1코드 번호나 이름으로 검색합니다.
- 2설명을 읽고 클라이언트·서버 중 어느 쪽 문제인지 가늠합니다.
자주 묻는 질문
다릅니다. gRPC는 HTTP/2 위에서 동작하지만 애플리케이션 수준 결과는 0~16번의 독자적인 상태 코드 체계로 나타냅니다. HTTP 상태 코드는 전송 계층의 결과만 나타냅니다.
맞습니다. 0(OK)만 성공이고 1~16번은 모두 실패를 나타냅니다.
UNKNOWN(2)은 어느 에러 공간에도 속하지 않는, 원인을 알 수 없는 에러입니다. INTERNAL(13)은 시스템이 기대하는 불변조건이 깨졌다는, 서버 내부 버그에 가까운 심각한 에러입니다.
알아두면 좋은 점
- gRPC 공식 문서(grpc.io/docs/guides/status-codes)와 GitHub grpc/grpc 저장소의 statuscodes.md를 대조해 코드 번호·이름·설명을 확인했습니다(2026-09-05, grpc.io 자체는 WebFetch가 막혀 열지 못해 GitHub 원문으로 대조했습니다).
- 이 코드는 gRPC 애플리케이션 계층 상태이며, 전송에 쓰인 HTTP/2 자체의 상태와는 별개입니다.
함께 보면 좋은 도구
마지막 검증: 2026년 9월 5일 · 결과는 참고용 추정치입니다.