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")
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.
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