Error handling

How gRPC deals with errors, and gRPC error codes.

Error handling

How gRPC deals with errors, and gRPC error codes.

Standard error model

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

If an error occurs, gRPC returns one of its error status codes instead, with an optional 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 of the gRPC data format (whether protocol buffers or something else). You may have noticed that it’s quite limited and doesn’t include the ability to communicate error details.

If you’re using protocol buffers as your data format, however, you may wish to consider using the richer error model developed and used by Google as described here. This model enables servers to return and clients to consume additional error details expressed as one or more protobuf messages. It further specifies a standard set of error message types to cover the most common needs (such as invalid parameters, quota violations, and stack traces). The protobuf binary encoding of this extra error information is provided as trailing metadata in the response.

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

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

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

  • Library implementations of the extended error model may not be consistent across languages in terms of requirements for and expectations of the error details payload
  • Existing proxies, loggers, and other standard HTTP request processors don’t have visibility into the error details and thus wouldn’t be able to leverage them for monitoring or other purposes
  • Additional error detail in the trailers interferes with head-of-line blocking, and will decrease HTTP/2 header compression efficiency due to more frequent cache misses
  • Larger error detail payloads may run into protocol limits (like max headers size), effectively losing the original error

Error status codes

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

General errors

CaseStatus code
Client application cancelled the requestGRPC_STATUS_CANCELLED
Deadline expired before server returned statusGRPC_STATUS_DEADLINE_EXCEEDED
Method not found on serverGRPC_STATUS_UNIMPLEMENTED
Server threw an exception (or did something other than returning a status code to terminate the RPC)GRPC_STATUS_UNKNOWN

Network failures

CaseStatus code
No data transmitted before deadline expires. Also applies to cases where some data is transmitted and no other failures are detected before the deadline expiresGRPC_STATUS_DEADLINE_EXCEEDED
Some data transmitted (for example, the request metadata has been written to the TCP connection) before the connection breaksGRPC_STATUS_UNAVAILABLE

Protocol errors

CaseStatus code
Could not decompress but compression algorithm supportedGRPC_STATUS_INTERNAL
Compression mechanism used by client not supported by the serverGRPC_STATUS_UNIMPLEMENTED
Flow-control resource limits reachedGRPC_STATUS_RESOURCE_EXHAUSTED
Flow-control protocol violationGRPC_STATUS_INTERNAL
Error parsing returned statusGRPC_STATUS_UNKNOWN
Unauthenticated: credentials failed to get metadataGRPC_STATUS_UNAUTHENTICATED
Invalid host set in authority metadataGRPC_STATUS_UNAUTHENTICATED
Error parsing response protocol bufferGRPC_STATUS_INTERNAL
Error parsing request protocol bufferGRPC_STATUS_INTERNAL

Language Support

Examples code is avilable for multiple languages on how to deal with standard errors as well as with the richer error details.

C++C++ error handling example
C++ error details example
GoGo error handling example
Go error details example
JavaJava error handling example
Java error details example
NodeNode error handling example
PythonPython error details example

The grpc-errors repo also contains additional error handling examples.

Last modified February 29, 2024: Status Codes user guide (#1263) (fb661d4)