Error Handling

This page describes how gRPC deals with errors, including gRPC's built-in error codes. Example code in different languages can be found here.

Standard error model

As you’ll have seen in our concepts document and examples, when a gRPC callcompletes successfully the server returns an OK status to the client(depending on the language the OK status may or may not be directly used inyour code). But what happens if the call isn’t successful?

If an error occurs, gRPC returns one of its error status codes instead, with anoptional string error message that provides further details about what happened.Error information is available to gRPC clients in all supported languages.

Richer error model

The error model described above is the official gRPC error model,is supported by all gRPC client/server libraries, and is independent ofthe gRPC data format (whether protocol buffers or something else). Youmay have noticed that it’s quite limited and doesn’t include theability to communicate error details.

If you’re using protocol buffers as your data format, however, you maywish to consider using the richer error model developed and usedby Google as describedhere. Thismodel enables servers to return and clients to consume additionalerror details expressed as one or more protobuf messages. It furtherspecifies astandard set of error messagetypesto cover the most common needs (such as invalid parameters, quotaviolations, and stack traces). The protobuf binary encoding of thisextra error information is provided as trailing metadata in theresponse.

This richer error model is already supported in the C++, Go, Java,Python, and Ruby libraries, and at least the grpc-web and Node.jslibraries have open issues requesting it. Other language libraries mayadd support in the future if there’s demand, so check their githubrepos if interested. Note however that the grpc-core library writtenin C will not likely ever support it since it is purposely data formatagnostic.

You could use a similar approach (put error details in trailingresponse metadata) if you’re not using protocol buffers, but you’dlikely need to find or develop library support for accessing this datain order to make practical use of it in your APIs.

There are important considerations to be aware of when deciding whether touse such an extended error model, however, including:

• Library implementations of the extended error model may not be consistentacross languages in terms of requirements for and expectations of the errordetails payload
• Existing proxies, loggers, and other standard HTTP requestprocessors don’t have visibility into the error details and thuswouldn’t be able to leverage them for monitoring or other purposes
• Additional error detail in the trailers interferes with head-of-lineblocking, and will decrease HTTP/2 header compression efficiency due tomore frequent cache misses
• Larger error detail payloads may run into protocol limits (likemax headers size), effectively losing the original error

Error status codes

Errors are raised by gRPC under various circumstances, from network failures tounauthenticated connections, each of which is associated with a particularstatus code. The following error status codes are supported in all gRPClanguages.

General errors

Network failures

Protocol errors