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