gRPC Status Code Reference

gRPC defines 17 status codes: OK (0), CANCELLED (1), UNKNOWN (2), INVALID_ARGUMENT (3), DEADLINE_EXCEEDED (4), NOT_FOUND (5), ALREADY_EXISTS (6), PERMISSION_DENIED (7), RESOURCE_EXHAUSTED (8), FAILED_PRECONDITION (9), ABORTED (10), OUT_OF_RANGE (11), UNIMPLEMENTED (12), INTERNAL (13), UNAVAILABLE (14), DATA_LOSS (15), and UNAUTHENTICATED (16). Each has a defined HTTP equivalent for transcoding.

UNAUTHENTICATED (code 16, HTTP 401) means the client has not provided authentication credentials or the credentials are invalid. PERMISSION_DENIED (code 7, HTTP 403) means the client is authenticated but does not have permission to perform the requested operation. In other words: UNAUTHENTICATED is "who are you?", while PERMISSION_DENIED is "I know who you are, but you cannot do this."

HTTP 499 is a non-standard code used by Nginx to indicate that the client closed the connection before the server responded. The gRPC CANCELLED status (code 1) means the client cancelled the RPC in flight, which is conceptually similar to a client dropping the connection. Google adopted HTTP 499 as the canonical transcoding mapping for CANCELLED. It does not appear in the RFC 7231 HTTP specification but is widely understood in modern infrastructure.

RESOURCE_EXHAUSTED (code 8, HTTP 429) indicates that a resource has been exhausted — most commonly a rate limit or quota. Return this code when a client exceeds their allowed request rate, when a server-side resource pool is full, or when a quota has been reached. Clients should implement exponential backoff and retry when they receive this status. It is the gRPC equivalent of HTTP 429 Too Many Requests.

FAILED_PRECONDITION (code 9) means the system is not in the required state to execute the operation — for example, trying to delete a non-empty directory. ABORTED (code 10) is used for operations that were aborted due to a concurrency conflict, such as a failed compare-and-swap or transaction abort. UNAVAILABLE (code 14) means the service is temporarily unavailable and the operation can be retried. FAILED_PRECONDITION and ABORTED are typically not retriable without fixing the precondition, while UNAVAILABLE is always safe to retry.

DEADLINE_EXCEEDED (code 4, HTTP 504) means the operation did not complete within the deadline set by the caller. In client code, you should distinguish it from CANCELLED: DEADLINE_EXCEEDED means the server may or may not have processed the request before the deadline expired, so the operation's state is unknown. For idempotent operations (like reads), it is usually safe to retry with a new deadline. For non-idempotent operations (like writes), check the server state before retrying to avoid duplicate side effects.

INTERNAL (code 13, HTTP 500) indicates that some invariant expected by the underlying system has been broken. It is the gRPC equivalent of a generic server-side error. Unlike UNKNOWN (code 2, HTTP 500), which is used for truly unknown errors or errors from sub-systems that don't use gRPC status codes, INTERNAL is used when the server detects a specific internal inconsistency or programming error. Clients generally should not retry INTERNAL errors without investigation.

Yes. The HTTP mappings shown in this table follow the canonical mappings documented in the gRPC HTTP/JSON transcoding specification and the grpc-gateway project defaults. When using grpc-gateway to expose a gRPC service as a REST API, or when using Envoy's gRPC-JSON transcoding filter, these are the HTTP status codes that will be returned for each gRPC error status by default. Some gateways allow you to override specific mappings via proto annotations.