gRPC Status Codes Reference

How to use it

1. Press / to focus the search field, then type what you have: the bare number from the error, a name like UNAVAILABLE, or a constant pasted from a stack trace — codes.Unavailable and grpc.StatusCode.CANCELLED both resolve.
2. Read the row: the meaning column is transcribed from the official statuscodes doc, the retry column is a cited posture rather than a promise, and the HTTP column shows what grpc-gateway would answer for a REST client.
3. Follow a code's anchor for the deep entry — the common causes, the retry note in full, and the constant for each of five languages with a copy button beside it.
4. Link a teammate straight to one code with its plain anchor, like #code-14. The Copy-link button shares only the view — what you typed in the search field is never encoded into a URL.

Your call failed with code 14 and the middle of an incident is no time to grep a proto file. This page lists all 17 canonical gRPC status codes with meaning, retry posture, common causes, per-language constants and the grpc-gateway HTTP mapping — every row cited to grpc.io sources. Search by number, name or a pasted constant; the lookup never leaves this page.

How it works

A gRPC status is not an HTTP status. When a call ends, the server reports the outcome in HTTP/2 trailers: grpc-status carries the numeric code and grpc-message a percent-encoded description. The HTTP-level :status is 200 even when the call failed — which is why a balancer that only watches HTTP codes can call a service healthy while every RPC inside it returns 14.

The canonical band is small on purpose. google.rpc.Code defines exactly 17 values, 0 through 16, shared by every implementation; nothing above the band is a gRPC status code. Services attach richer detail — retry delays, quota violations, field errors — in the grpc-status-details-bin trailer instead of minting new numbers.

Deadlines travel with the call: the client sets one, the grpc-timeout header propagates it hop by hop, and whichever hop runs out first answers 4 DEADLINE_EXCEEDED — so the code often names the slowest dependency in the chain, not the service you dialed. The retry postures in this table follow the gRPC retry design, which singles out 14 UNAVAILABLE as the code to retry with exponential backoff.

A browser page cannot open a native gRPC channel: browser HTTP APIs expose no HTTP/2 trailers, and grpc-web exists precisely because a translation layer — the server itself or a proxy in front of it — must sit in the middle. This reference is therefore a static, cited table — the search runs over rows already on the page, and no lookup can or does call out.

Examples

14

14 UNAVAILABLE · Retry with backoff · HTTP 503 via grpc-gateway

deadline

4 DEADLINE_EXCEEDED · Sometimes — see note · HTTP 504 via grpc-gateway

20

That number is not a gRPC status code — the canonical codes run 0 through 16, and google.rpc.Code defines nothing outside that band. An HTTP-looking number belongs to the HTTP column, not the code column.

Every example on this page is executed against the same engine that powers the tool, on every build.

Common errors

That query is longer than 64 characters — only its first 64 were read. A gRPC status code is at most two digits and no canonical status name is longer than 19 characters.

The cap refusal. The field never silently clips: the lookup reads the first 64 characters, answers from them, and says so.

An empty search is not an error — the full table of 17 status codes is shown.

Not a failure state at all: the resting state of a reference page is the whole reference. The typed note exists so engine consumers get an explanation instead of a silent default.

That number is not a gRPC status code — the canonical codes run 0 through 16, and google.rpc.Code defines nothing outside that band. An HTTP-looking number belongs to the HTTP column, not the code column.

The refusal for 17, 100, 503 and negatives alike. The canonical band is closed, so an out-of-band number is answered by teaching, never by a guessed row.

Nothing on this page matches that — all 17 canonical gRPC status codes are listed here, so try the number, the SCREAMING_SNAKE name, or a word from a meaning.

The zero-result state names its own way out. Nothing dead-ends: clearing the field restores the full table instantly.

Keyboard shortcuts

/

Focus the search field