gRPC & ASP.NET Core 3.1: Global error Handling in gRPC & gRPC status codes

Global error Handling server side

Microsoft has implemented Interceptors, they are similar to Filters or Middlewares in ASP.NET Core MVC or WebAPI, they can be used for global exception handling, logging, validation etc.

Here is my own implementation of my server side Interceptor, Continuation is a Task that must be awaited, then if any Exception has been raised, then you can control the RpcException and the associated StatusCode depending on the Exception you got:

Don’t forge to register it like this in the Startup.cs:

The second way (not the best way) is to encapsulate all your services by a try / catch block, and the Exception type to use is also RpcException, like the Interceptor above:

In this sample we passed Status.DefaultCancelled status, it’s a static method shortcut for the struct Status, you can find in the table below the enumeration of its possible values:

Name Description

The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.


Some entity that we attempted to create (e.g., file or directory) already exists.


The operation was cancelled (typically by the caller).


Unrecoverable data loss or corruption.


Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.


Operation was rejected because the system is not in a state required for the operation’s execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc.


Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken.


Client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).


Some requested entity (e.g., file or directory) was not found.


Not an error; returned on success.


Operation was attempted past the valid range. E.g., seeking or reading past end of file.


The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors).


Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.


The request does not have valid authentication credentials for the operation.


The service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.


Operation is not implemented or not supported/enabled in this service.


Unknown error. An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.


RpcException has overloads that gives you the interesting possiblity to customize your errors:

You can enrich your response error with Trailers that are custom metadata. Example of a RpcException enriched with custom metadata:

Demo client side with a simple try / catch block:

Global error Handling client side

Client side it’s also possible to handle errors via an Interceptor (implementing client side events such as AsyncUnaryCall):

Here is how to update consequently the .NET client, example with console using ILogger and dependency injection :

Demo client side:


We saw in this article how to handle errors globally. The usage of Interceptor, RpcException, StatusCodes and Trailers gives us a certain flexibility, like customizing errors and the possibility to send relevant errors to the client.

It’s not implemented yet in gRPC ASP.NET Core, but Google has developed a promising richer model like FaultContract for WCF:

See you in the next article to learn how to implement resiliency with Polly ! 🙂

Written by


Anthony is a specialist in Web technologies (14 years of experience), in particular Microsoft .NET and learns the Cloud Azure platform. He has received twice the Microsoft MVP award and he is also certified Microsoft MCSD and Azure Fundamentals.
%d bloggers like this: