How do I handle errors and exceptions in gRPC services in .NET?

Introduction

In real-world applications, things don’t always go as planned. Requests can fail, data may be invalid, or services might be unavailable. That’s why proper error handling is very important when building gRPC services in .NET.

In this article, we will understand how error handling works in gRPC, how it is different from REST, and how to implement it properly in ASP.NET Core using simple and clear examples.

How Error Handling Works in gRPC

Unlike REST APIs where errors are usually returned as HTTP status codes (like 404 or 500), gRPC uses its own error model.

In gRPC:

Errors are represented using status codes
Each error has a status code and a message
Errors are sent using RpcException

This makes error handling more structured and consistent across services.

gRPC Status Codes

Some commonly used gRPC status codes are:

OK: Request was successful
InvalidArgument: The input data is wrong
NotFound: Resource not found
Unauthenticated: User is not logged in
PermissionDenied: User does not have access
Internal: Server error

These codes help the client understand what went wrong.

Throwing Errors in gRPC Service

In .NET, you handle errors by throwing an RpcException.

public override Task<MyResponse> GetData(MyRequest request, ServerCallContext context)
{
    if (string.IsNullOrEmpty(request.Name))
    {
        throw new RpcException(new Status(StatusCode.InvalidArgument, "Name is required"));
    }

    return Task.FromResult(new MyResponse
    {
        Message = "Success"
    });
}

Here:

We check if the input is valid
If not, we throw an error with a proper status code

Handling Errors on Client Side

The client should also handle errors properly.

try
{
    var response = await client.GetDataAsync(new MyRequest());
}
catch (RpcException ex)
{
    Console.WriteLine($"Error: {ex.Status.Detail}");
    Console.WriteLine($"Code: {ex.StatusCode}");
}

This allows the client to:

Read the error message
Take action based on the error type

Using Interceptors for Global Error Handling

Instead of handling errors in every method, you can use interceptors.

public class ExceptionInterceptor : Interceptor
{
    public override async Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
        TRequest request,
        ServerCallContext context,
        UnaryServerMethod<TRequest, TResponse> continuation)
    {
        try
        {
            return await continuation(request, context);
        }
        catch (Exception ex)
        {
            throw new RpcException(new Status(StatusCode.Internal, "Something went wrong"));
        }
    }
}

builder.Services.AddGrpc(options =>
{
    options.Interceptors.Add<ExceptionInterceptor>();
});

This helps you manage errors in one central place.

Best Practices for Error Handling

Always return meaningful error messages
Use correct status codes
Avoid exposing sensitive information
Use interceptors for global handling
Log errors for debugging

These practices make your application more reliable and easier to maintain.

Common Mistakes to Avoid

Returning generic errors without details
Using wrong status codes
Not handling exceptions on client side
Exposing internal server details

Avoiding these mistakes improves your API quality.

When Proper Error Handling Matters

Error handling is especially important in:

Microservices
Distributed systems
APIs used by multiple clients

Without proper error handling, debugging becomes very difficult.

Summary

Error handling in gRPC .NET is based on structured status codes and RpcException. Unlike REST, it provides a consistent and strongly typed way to communicate errors between client and server. By using proper status codes, handling exceptions correctly, and applying global error handling using interceptors, you can build robust and production-ready gRPC services.