gRPC Error Handling and Status Codes
On this page
gRPC status codes and when to use each
HTTP has hundreds of status codes; gRPC has 17. Every call ends with one, plus a message and optional details. Because the set is small and shared across every language, clients can handle errors uniformly.
| Code | Use when | Client should |
|---|---|---|
OK | Success | |
INVALID_ARGUMENT | The request is malformed whatever the system state | Fix the request; don't retry |
NOT_FOUND | The requested entity doesn't exist | Not retry |
ALREADY_EXISTS | Creating something that exists | Not retry |
FAILED_PRECONDITION | System isn't in the right state (cancel a shipped order) | Not retry until state changes |
PERMISSION_DENIED | Authenticated, not allowed | Not retry |
UNAUTHENTICATED | Missing or invalid credentials | Refresh credentials |
RESOURCE_EXHAUSTED | Quota or rate limit, or message too large | Back off |
ABORTED | Concurrency conflict (optimistic locking) | Retry the whole transaction |
UNAVAILABLE | Temporarily unavailable | Retry with backoff (Day 22) |
DEADLINE_EXCEEDED | Deadline passed | Maybe retry, if idempotent |
CANCELLED | The caller cancelled | Nothing |
UNIMPLEMENTED | Method not implemented | Not retry |
INTERNAL | A bug or broken invariant | Not retry blindly; investigate |
UNKNOWN | Unmapped error, often a raw error returned from a handler | Investigate |
DATA_LOSS, OUT_OF_RANGE | Unrecoverable data loss; past the valid range |
Common mistakes: returning plain errors (which become UNKNOWN), using INTERNAL for bad input, and UNAVAILABLE for permanent failures, which makes clients retry forever.
Returning gRPC errors in Go
o, ok := s.orders[req.GetOrderId()]
if !ok {
return nil, status.Errorf(codes.NotFound, "order %q not found", req.GetOrderId())
}Rich error details with errdetails
A message string is for humans. For machines, attach error details: standard messages from google.rpc such as BadRequest (field violations), ErrorInfo (a reason and domain), RetryInfo (when to retry), QuotaFailure and PreconditionFailure.
st := status.New(codes.InvalidArgument, "order_id is required")
st, _ = st.WithDetails(&errdetails.BadRequest{
FieldViolations: []*errdetails.BadRequest_FieldViolation{
{Field: "order_id", Description: "must not be empty"}}})
return nil, st.Err()grpcurl shows the details travelling with the status:
ERROR:
Code: InvalidArgument
Message: order_id is required
Details:
1) {
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [ { "field": "order_id", "description": "must not be empty" } ]
}And the Go client reads them as typed values:
st := status.Convert(err)
for _, d := range st.Details() {
if br, ok := d.(*errdetails.BadRequest); ok {
for _, v := range br.GetFieldViolations() {
fmt.Printf("code=%s field=%s problem=%q\n", st.Code(), v.GetField(), v.GetDescription())
}
}
}error details: code=InvalidArgument field=order_id problem="must not be empty"Propagating errors across services
When service A calls B and B fails, don't forward B's status blindly: B's NOT_FOUND for an internal lookup might mean A has an INTERNAL bug, and B's INVALID_ARGUMENT means A built a bad request. Translate errors at each boundary, and never put internal details (stack traces, SQL) in messages that reach external callers.
Check yourself
INVALID_ARGUMENT means the request is wrong regardless of state; FAILED_PRECONDITION means the request is valid but the system isn't in a state that allows it.
Clients and retry policies treat UNAVAILABLE as transient and retry, wasting resources on both sides and delaying the caller learning about the real failure. Use a code that matches the cause, like NOT_FOUND or INVALID_ARGUMENT.
From typed details such as google.rpc.BadRequest attached to the status, which list each field violation with a description. Clients extract them with the status package instead of parsing messages.
Rarely as is. Map downstream errors to codes that make sense for your caller, for example a downstream NOT_FOUND may mean INTERNAL for you.
UNAUTHENTICATED means the caller's identity is missing or invalid, such as an expired token, so getting new credentials may help. PERMISSION_DENIED means the identity is known but not allowed to do this, so retrying with the same identity won't.