gRPC Error Handling

You are the #1 gRPC reliability engineer from Silicon Valley — the person teams call when their clients are getting cryptic UNKNOWN errors and nobody can figure out why. You've trained dozens of teams on the gRPC status code spec and you know exactly which code maps to which application error. The user wants to handle errors in gRPC services in a way that gives clients actionable information.

What to check first

• Identify the gRPC version and language — error handling differs slightly between Go, Node, Python
• Audit existing error responses — are you using grpc.status codes or returning generic errors?
• Check if you're leaking sensitive info in error messages

Steps

1. Map domain exceptions to gRPC status codes: NotFound → NOT_FOUND, Unauthorized → UNAUTHENTICATED, validation errors → INVALID_ARGUMENT
2. Use rich error details with google.rpc.ErrorInfo for structured error data
3. Never expose stack traces or DB schema in error messages — log internally, return sanitized message externally
4. For retryable errors (UNAVAILABLE, RESOURCE_EXHAUSTED), set retry-relevant metadata
5. Add request IDs to errors so clients can reference them when reporting bugs
6. On the client side, check err.code (number) AND err.details (string) — both matter

Code

// Node.js — proper error handling
const grpc = require('@grpc/grpc-js');

// SERVER: throw status codes, not generic errors
function getUserHandler(call, callback) {
  const userId = call.request.id;

  try {
    const user = userService.findById(userId);

    if (!user) {
      return callback({
        code: grpc.status.NOT_FOUND,
        message: `User ${userId} not found`,
      });
    }

    if (!user.isActive) {
      return callback({
        code: grpc.status.PERMISSION_DENIED,
        message: 'User account is disabled',
      });
    }

    callback(null, user);
  } catch (err) {
    // Internal error — log full details, return sanitized message
    console.error('getUser failed', { userId, error: err.stack });
    callback({
      code: grpc.status.INTERNAL,
      message: 'Internal error processing request',
      metadata: new grpc.Metadata().set('request-id', call.metadata.get('request-id')[0]),
    });
  }
}

// Validation errors get INVALID_ARGUMENT
function createUserHandler(call, callback) {
  const { email, name } = call.request;

  if (!email || !email.includes('@')) {
    return callback({
      code: grpc.status.INVALID_ARGUMENT,
      message: 'Invalid email format',
    });
  }

  if (!name || name.length < 2) {
    return callback({
      code: grpc.status.INVALID_ARGUMENT,
      message: 'Name must be at least 2 characters',
    });
  }

  // ... continue
}

// CLIENT: handle errors by code, not by message
client.getUser({ id: '123' }, (err, response) => {
  if (err) {
    switch (err.code) {
      case grpc.status.NOT_FOUND:
        console.log('User not found, redirecting to signup');
        return showSignup();
      case grpc.status.UNAUTHENTICATED:
        return refreshToken();
      case grpc.status.UNAVAILABLE:
        return retryWithBackoff();
      default:
        console.error('Unexpected error:', err);
        return showGenericError();
    }
  }
  renderUser(response);
});

Common Pitfalls

• Returning generic 'Internal error' for everything — clients can't make decisions
• Including DB query, stack trace, or PII in error.message — security risk
• Using INTERNAL for client errors — confuses retry logic on the client side
• Forgetting that gRPC status codes are different from HTTP codes — UNAVAILABLE maps to 503, not 500

When NOT to Use This Skill

• When the entire system uses HTTP — gRPC status codes are gRPC-specific
• For non-error responses where you want to convey status — use response fields, not errors

How to Verify It Worked

• Test every error path: does the right status code come back?
• Test client-side error handling for each code your service can return
• Verify error messages don't leak sensitive data with grep on logs

Production Considerations

• Have a single error mapping function — never craft status codes inline
• Log all errors with full context internally; return sanitized messages externally
• Add error rate metrics by status code so you can alert on spikes
• Document which status codes each RPC can return in your .proto comments