gRPC Error Handling
You'll learn to
- -Use gRPC's standard status codes correctly instead of overloading a generic error for everything
- -Attach rich, structured error detail using google.rpc.Status instead of just a plain error string
gRPC has its own status code system, conceptually parallel to HTTP's but with a different, RPC-oriented vocabulary - and just like REST's 4xx/5xx taxonomy, using the right specific code (instead of one generic failure for everything) is what lets calling code react correctly without parsing an error string.
The Standard gRPC Status Codes
- -`NOT_FOUND`: the requested resource doesn't exist - the gRPC analog of HTTP 404.
- -`INVALID_ARGUMENT`: the request itself was malformed or failed validation - analog of 400/422.
- -`PERMISSION_DENIED`: the caller is known but not allowed to perform this action - analog of 403.
- -`UNAUTHENTICATED`: the caller's identity couldn't be established - analog of 401.
- -`ALREADY_EXISTS`: a create-style call conflicts with existing state - analog of 409.
- -`UNAVAILABLE`: the service is temporarily down or overloaded - safe to retry, the analog of a 503 or transient 5xx.
- -`DEADLINE_EXCEEDED`: the call didn't complete within its deadline (covered in depth next chapter).
Notice the direct parallel to the REST status code taxonomy from earlier in this course - the underlying design problem (letting a caller react programmatically to the category of failure) is the same, gRPC just has its own vocabulary for it, tuned for RPC semantics rather than HTTP's document-transfer origins.
google.rpc.Status: Structured Detail Beyond a Status Code
import "google/rpc/status.proto";
import "google/rpc/error_details.proto";
// A status code alone (INVALID_ARGUMENT) doesn't say WHICH fields failed.
// google.rpc.Status carries a message plus a list of typed "details":
message BadRequest {
message FieldViolation {
string field = 1;
string description = 2;
}
repeated FieldViolation field_violations = 1;
}This is the gRPC equivalent of the field-level validation errors from the REST error-design chapter - a bare `INVALID_ARGUMENT` status code tells the caller the category of failure but not which specific fields were wrong or why. `google.rpc.Status`'s `details` field carries structured, typed error information (like the `BadRequest.FieldViolation` list above) alongside the status code, giving the caller everything it needs to react precisely, the same actionable-error principle from the RFC 7807 chapter, expressed in protobuf's own typed error model instead.
Retriable vs. non-retriable status codes matter for building correct client retry logic: `UNAVAILABLE` and `DEADLINE_EXCEEDED` are often safe to retry (the failure may have been transient), while `INVALID_ARGUMENT` and `PERMISSION_DENIED` will fail identically on every retry, since retrying doesn't fix a malformed request or a permissions problem - blindly retrying every failure wastes effort on the calls that can never succeed by simply trying again.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design Error Dimensions in the API Design Lab's gRPC & Event-Driven act.