Status

The gRPCity library provides a convenient way to obtain status. In general, you won’t need to use it often, but I’ll provide a brief overview here.

Get Status

Obtaining the Status object by grpcity:

import { Status } from 'grpcity'
 
console.log(Status.OK)

Obtaining the status returned by the server is straightforward for the client, as shown below:

const client = clients.get('path.to.service')
const { status } = await client.rpcMethod()
console.log(status)
 
 
// The printed result after execution
{
    code: 0,
    details: 'OK',
    metadata: Metadata { internalRepr: Map(0) {}, options: {} }
}

Status Codes

The default status codes and their descriptions are as follows:

Code	Number	Description
OK	0	No error; indicates a successful return.
CANCELLED	1	The operation was cancelled, typically by the caller.
UNKNOWN	2	Unknown error. For example, when a status value received from a different address space is unknown within this address space, this error may be returned. It may also be used to translate errors that are not returned with sufficient detail by APIs.
INVALID_ARGUMENT	3	The client specified an invalid argument. Note that this differs from “FAILED_PRECONDITION.” “INVALID_ARGUMENT” indicates arguments that are problematic regardless of the system state (e.g., a file format error).
DEADLINE_EXCEEDED	4	The deadline expired before the operation could complete. For operations that change the system state, this error may be returned even if the operation has completed successfully. For example, a successful response from a server that was delayed long enough for the client to disconnect may lead to this error.
NOT_FOUND	5	Some requested entity (e.g., file or directory) was not found. Server developers should consider returning “NOT_FOUND” if an RPC should be rejected for an entire class of users, such as gradual feature rollout or undocumented whitelist. If a request is rejected for some users in a user class based on, for example, user-based access control, “PERMISSION_DENIED” must be used.
ALREADY_EXISTS	6	The client attempted to create an entity (e.g., a file or directory) that already exists.
PERMISSION_DENIED	7	The caller does not have permission to execute the specified operation. “PERMISSION_DENIED” must not be used for errors caused by exhausting some resource (use “RESOURCE_EXHAUSTED” instead). “PERMISSION_DENIED” must not be used if the caller cannot be identified.
RESOURCE_EXHAUSTED	8	Some resource has been exhausted, such as a per-user quota, or the entire file system is out of space.
FAILED_PRECONDITION	9	The operation was rejected because the system is not in a state required for the operation. For example, an attempt to delete a directory that is non-empty, even though it is a directory, would result in “FAILED_PRECONDITION.” Service implementers can use the following guidelines to choose between “FAILED_PRECONDITION,” “ABORTED,” and “UNAVAILABLE”: (a) If the client can retry the failed call, use “UNAVAILABLE.” (b) If the client should not retry at a higher level, use “ABORTED” (for example, when a client specifies a test and the set fails). (c) If the client should not retry until the system state is fixed, use “FAILED_PRECONDITION.” For example, if a directory is not empty, “rmdir” should fail because the client should not retry unless it first removes the files from the directory.
ABORTED	10	The operation was aborted, typically due to a concurrency issue, such as a sequencer check failure or a transaction abort. Service implementers can use the following guidelines to choose between “FAILED_PRECONDITION,” “ABORTED,” and “UNAVAILABLE”: (a) If the client can retry the failed call, use “UNAVAILABLE.” (b) If the client should retry at a higher level, use “ABORTED” (for example, when a client specifies a test and the set fails). (c) If the client should not retry until the system state is fixed, use “FAILED_PRECONDITION.” For example, “rmdir” might fail if it is called on a non-empty directory, but the client should not retry until it removes the files from the directory.
OUT_OF_RANGE	11	The operation was attempted past the valid range. For example, reading or writing past the end of a file. Unlike “INVALID_ARGUMENT,” this error indicates a problem that may be fixed if the system state changes. For example, if a 32-bit file system is asked to read at a certain offset that is not in the range [0,2^32-1], it will generate “INVALID_ARGUMENT,” but if asked to read from an offset that is past the current file size, it will generate “OUT_OF_RANGE.” “RESUMED: FAILED_PRECONDITION” and “OUT_OF_RANGE” have a small overlap. We recommend using “OUT_OF_RANGE” (the more specific error) when it is applicable so that callers who iterate through space can easily locate “OUT_OF_RANGE” errors.
UNIMPLEMENTED	12	The operation is not implemented or not supported/enabled in this service.
INTERNAL	13	Internal error. This means that some invariant expected by the underlying system has been broken. This error code is reserved for serious errors.
UNAVAILABLE	14	The service is currently unavailable. This is most likely a transient condition that can be corrected by retrying with an exponential backoff. Note that it is not always safe to retry non-idempotent operations.
DATA_LOSS	15	Unrecoverable data loss or corruption.
UNAUTHENTICATED	16	The request does not have valid authentication credentials.

Status Cases

In addition to “OK,” you should also be aware of the possible reasons for other Code values, as shown in the following table:

Case	Code	Client or Server
The client’s application cancelled the request	CANCELLED	Both
The deadline expired before the server returned a status	DEADLINE_EXCEEDED	Both
The method was not found on the server	UNIMPLEMENTED	Server
The server is shutting down	UNAVAILABLE	Server
The server application throws an exception (or performs an action other than returning a status code, terminating the RPC)	UNKNOWN	Server
The deadline expired before a response was received. This can happen when the client is unable to send the request to the server or the server is slow to respond.	DEADLINE_EXCEEDED	Both
Some data was sent before the connection was terminated (e.g. writing request metadata to the TCP connection)	UNAVAILABLE	Client
The server was unable to decompress data, although the compression algorithm was supported (client to server)	INTERNAL	Server
The server was unable to decompress data, although the compression algorithm was supported (server to client)	INTERNAL	Client
The compression mechanism used by the client is not supported on the server	UNIMPLEMENTED	Server
The server’s temporary resources are exhausted (e.g. reaching the rate-limiting resource limit)	RESOURCE_EXHAUSTED	Server
The client does not have enough memory to store the server’s response	RESOURCE_EXHAUSTED	Client
A traffic control protocol violation occurred	INTERNAL	Both
An error occurred while parsing the returned status	UNKNOWN	Client
Invalid authentication metadata (credentials couldn’t be obtained from the metadata, incompatible credentials set on the channel and call, invalid host set in `:authority` metadata, etc.)	UNAUTHENTICATED	Both
Request cardinality violation (method requires exactly one request, but the client sent a different number of requests)	UNIMPLEMENTED	Server
Response cardinality violation (method requires exactly one response, but the server sent a different number of responses)	UNIMPLEMENTED	Client
An error occurred while parsing the response protocol	INTERNAL	Client
An error occurred while parsing the request protocol	INTERNAL	Server
Messages sent or received were larger than the configured limit	RESOURCE_EXHAUSTED	Both
Keepalive monitor timeout	UNAVAILABLE	Both

Credentials Error