How many gRPC status codes are there?

There are 17 canonical codes, numbered 0 through 16. OK is 0 and the highest is UNAUTHENTICATED at 16. Code values are stable and defined in the grpc-status spec.

Which gRPC codes are safe to retry?

UNAVAILABLE (14) is the classic retryable code, often with backoff. ABORTED (10) and RESOURCE_EXHAUSTED (8) may be retried with care. Codes like INVALID_ARGUMENT or NOT_FOUND should not be retried because the result will not change.

What is the difference between UNKNOWN and INTERNAL?

UNKNOWN (2) means an error occurred whose status could not be determined, often a non-gRPC error leaking through. INTERNAL (13) signals a serious invariant broken inside the system, like a serialization failure.

How do gRPC codes map to HTTP status codes?

The gRPC-Gateway and grpc-web map codes to HTTP, e.g. NOT_FOUND to 404, PERMISSION_DENIED to 403, UNAUTHENTICATED to 401 and UNAVAILABLE to 503. The mapping is conventional and documented in the gRPC HTTP gateway.

What does DEADLINE_EXCEEDED mean?

DEADLINE_EXCEEDED (4) means the operation did not complete before the client-set deadline. It may be returned even if the server eventually finished, so the operation's actual state can be ambiguous.

gRPC Status Codes — Gera Tools

gRPC status codes explained

Every gRPC call completes with a status consisting of a numeric code and an optional message. Unlike HTTP, gRPC defines a fixed, language-neutral set of 17 codes (0–16) that every implementation shares. This reference lists all of them with their numeric value, the conventional HTTP status they map to in gateways, a plain-language meaning, and whether the call is generally safe to retry.

How it works

gRPC status codes are defined in the grpc-status trailer of every response. Code 0 (OK) means success; any non-zero code is an error. The codes split roughly into three groups:

Client errors the caller should fix: INVALID_ARGUMENT (3), NOT_FOUND (5), PERMISSION_DENIED (7), FAILED_PRECONDITION (9), UNAUTHENTICATED (16).
Transient errors worth retrying: DEADLINE_EXCEEDED (4), RESOURCE_EXHAUSTED (8), ABORTED (10), UNAVAILABLE (14).
Server faults that signal bugs: UNKNOWN (2), INTERNAL (13), DATA_LOSS (15).

When a gRPC service is exposed over HTTP via a gateway, codes map to HTTP statuses by convention — NOT_FOUND becomes 404, UNAVAILABLE becomes 503, and so on. That mapping is shown per row so you can reason about both protocols at once.

Retry guidance and example

A safe retry policy retries only idempotent calls that failed with UNAVAILABLE, and uses exponential backoff:

attempt 1 -> wait 100ms
attempt 2 -> wait 200ms
attempt 3 -> wait 400ms (then give up)

Avoid retrying INVALID_ARGUMENT, NOT_FOUND or PERMISSION_DENIED — the inputs must change first. For RESOURCE_EXHAUSTED, honour any retry-delay the server returns rather than hammering it. Use the table below to confirm a code’s number and HTTP equivalent before wiring up interceptors.

gRPC Status Codes

Email me this result

gRPC status codes explained

How it works

Retry guidance and example