gRPC Error Handling with Status Codes
Fast recall
Quick revision
Core answer
Status codes (0–16) instead of HTTP status codes. The server signals errors by calling responseObserver.onError(StatusRuntimeException) or by closing the call with a non-OK Status. The client receives a StatusRuntimeException that it can catch and inspect. You should always map your domain exceptions to meaningful gRPC status codes rather than letting raw Java exceptions propagate.Checks that you understand gRPC's error model rather than assuming it works like HTTP.
Interviewers want to see you can communicate rich error information to clients and handle errors gracefully.
Interviewers want to see you can communicate rich error information to clients and handle errors gracefully.
Interview-ready guide
Interview answer
gRPC uses its own 17-status-code system for application errors, not HTTP status codes. Every gRPC call returns HTTP 200 at the transport layer — the actual result lives in the grpc-status trailer. Understanding these codes is essential for both server-side error mapping and client-side retry decisions.
Key status codes and their semantics:
NOT_FOUNDfor missing entities,INVALID_ARGUMENTfor bad input,PERMISSION_DENIEDfor authorization failures,UNAUTHENTICATEDfor missing credentialsUNAVAILABLEmeans transient failure — safe to retry with backoff;INTERNALmeans something is genuinely broken — retrying won't help; using the wrong one causes clients to either retry hopelessly or give up on recoverable failuresDEADLINE_EXCEEDEDsignals the client's deadline passed before the server responded — the correct signal for timeout scenarios
Centralized error mapping:
- On the server, signal errors by calling
responseObserver.onError()with aStatusRuntimeException; for larger services, centralize this with a global interceptor that catches domain exceptions and maps them to status codes — the same concept as Spring's@ControllerAdvice - The production rule: never let raw Java exceptions propagate to clients; an uncaught
NullPointerExceptionbecomesUNKNOWNwith the stack trace in the description — a security risk and useless to clients
Client-side error handling:
StatusRuntimeException.getStatus().getCode()is the client-side API; always switch on the code enum, not the description string which is human-readable and may change
I recommend logging the full stack trace server-side while keeping error descriptions informative but safe for clients — the goal is a client that can react programmatically to the code, not one that parses error messages.
gRPC Error Handling with Status Codes
Direct Answer
gRPC uses a well-defined set of Status codes (0–16) instead of HTTP status codes. The server signals errors by calling responseObserver.onError(StatusRuntimeException) or by closing the call with a non-OK Status. The client receives a StatusRuntimeException that it can catch and inspect. You should always map your domain exceptions to meaningful gRPC status codes rather than letting raw Java exceptions propagate.
Common Mistakes & Pitfalls
Interviewers want to see you can communicate rich error information to clients and handle errors gracefully.
Check your understanding
Answer these without looking back at the article.
- How do you attach structured error details to a gRPC error using `google.rpc.Status` and `ErrorInfo`?
- What is the difference between `UNAVAILABLE` and `INTERNAL` status codes in terms of retry behaviour?
- How do you propagate a gRPC error code across service boundaries in a microservices architecture?
Related interview prep categories
1Want a guided curriculum order?
These modules are also sequenced in our flagship backend interview track — open it when you prefer an ordered path instead of browsing by topic.