This page describes how gRPC deals with errors, including gRPC’s built-in error codes. Example code in different languages can be found here.
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.
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.
| Case | Status code |
|---|---|
| Client application cancelled the request | GRPC_STATUS_CANCELLED |
| Deadline expired before server returned status | GRPC_STATUS_DEADLINE_EXCEEDED |
| Method not found on server | GRPC_STATUS_UNIMPLEMENTED |
| Server shutting down | GRPC_STATUS_UNAVAILABLE |
| Server threw an exception (or did something other than returning a status code to terminate the RPC) | GRPC_STATUS_UNKNOWN |
| Case | Status 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 expires | GRPC_STATUS_DEADLINE_EXCEEDED |
| Some data transmitted (for example, the request metadata has been written to the TCP connection) before the connection breaks | GRPC_STATUS_UNAVAILABLE |
| Case | Status code |
|---|---|
| Could not decompress but compression algorithm supported | GRPC_STATUS_INTERNAL |
| Compression mechanism used by client not supported by the server | GRPC_STATUS_UNIMPLEMENTED |
| Flow-control resource limits reached | GRPC_STATUS_RESOURCE_EXHAUSTED |
| Flow-control protocol violation | GRPC_STATUS_INTERNAL |
| Error parsing returned status | GRPC_STATUS_UNKNOWN |
| Unauthenticated: credentials failed to get metadata | GRPC_STATUS_UNAUTHENTICATED |
| Invalid host set in authority metadata | GRPC_STATUS_UNAUTHENTICATED |
| Error parsing response protocol buffer | GRPC_STATUS_INTERNAL |
| Error parsing request protocol buffer | GRPC_STATUS_INTERNAL |