Skip to content
API Design Learn/gRPC Reliability
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

gRPC Error Handling

4 min read

You'll learn to

  • -Pick the right gRPC status code, and match it to its HTTP counterpart
  • -Retry only the codes that are worth retrying, and watch a client give up at once on the others
  • -Attach structured, field-level detail to a status, the gRPC form of a validation error

gRPC has its own set of status codes, parallel to HTTP's but with a vocabulary suited to remote procedure calls. And just as with REST, the point of using the right specific code, instead of one generic failure for everything, is that the calling code can react correctly without parsing an error string.

An Analogy: A Hospital Triage Tag

A triage tag on a patient is a single word that tells the next person what to do: treat now, wait, or send home. The tag is useful because the choices are few and everyone agrees on them. Status codes are the same. A client that sees UNAVAILABLE knows to try again soon. A client that sees INVALID_ARGUMENT knows trying again is pointless.

The Standard gRPC Status Codes

  • -NOT_FOUND: the requested resource does not exist, like HTTP 404.
  • -INVALID_ARGUMENT: the request was malformed or failed validation, like 400 or 422.
  • -PERMISSION_DENIED: the caller is known but not allowed to do this, like 403.
  • -UNAUTHENTICATED: the caller's identity could not be established, like 401.
  • -ALREADY_EXISTS: a create call conflicts with existing state, like 409.
  • -UNAVAILABLE: the service is temporarily down or overloaded. Safe to retry, like a 503.
  • -DEADLINE_EXCEEDED: the call did not finish within its deadline (the next chapter covers this).

Notice the parallel with the REST status codes chapter. The design problem is the same, letting a caller react to the category of failure in code, and gRPC has its own vocabulary for it.

google.rpc.Status: Detail Beyond a Status Code

Attaching rich, typed error detail to 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;
}

A bare INVALID_ARGUMENT tells the caller the category but not which field was wrong or why. The standard google.rpc.Status message carries a text message plus a list of typed details, such as the BadRequest list of field violations above. This is the gRPC form of field-level validation errors from the REST errors chapter, and of the actionable-error idea behind RFC 7807, expressed in protobuf's own typed model.

The demo has two parts. A client retries three different failures, and a validation error carries two field violations. Watch how many attempts each failure gets.

Press Run: UNAVAILABLE is retried, INVALID_ARGUMENT is not, and the details name each field

Retriable versus non-retriable matters for correct retry logic. UNAVAILABLE and DEADLINE_EXCEEDED are often safe to retry because the failure may have been transient. INVALID_ARGUMENT and PERMISSION_DENIED fail identically every time, since retrying does not fix a malformed request or a permissions problem. Retrying every failure blindly wastes effort on calls that can never succeed.

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.

Ready to Build This?

Design Error Dimensions in the API Design Lab's gRPC & Event-Driven act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!