grpc-go/Documentation/rpc-errors.md

RPC Errors

All service method handlers should return nil or errors from the status.Status type. Clients have direct access to the errors.

Upon encountering an error, a gRPC server method handler should create a status.Status. In typical usage, one would use status.New passing in an appropriate codes.Code as well as a description of the error to produce a status.Status. Calling status.Err converts the status.Status type into an error. As a convenience method, there is also status.Error which obviates the conversion step. Compare:

st := status.New(codes.NotFound, "some description")
err := st.Err()

// vs.

err := status.Error(codes.NotFound, "some description")

Adding additional details to errors

In some cases, it may be necessary to add details for a particular error on the server side. The status.WithDetails method exists for this purpose. Clients may then read those details by first converting the plain error type back to a status.Status and then using status.Details.

Example

The example demonstrates the API discussed above and shows how to add information about rate limits to the error message using status.Status.

To run the example, first start the server:

$ go run examples/rpc_errors/server/main.go

In a separate session, run the client:

$ go run examples/rpc_errors/client/main.go

On the first run of the client, all is well:

2018/03/12 19:39:33 Greeting: Hello world

Upon running the client a second time, the client exceeds the rate limit and receives an error with details:

2018/03/19 16:42:01 Quota failure: violations:<subject:"name:world" description:"Limit one greeting per person" >
exit status 1