gRPC Status Code Decoder

gRPC defines 17 canonical status codes (0–16) that every RPC call returns. Unlike HTTP which has ~70 status codes, gRPC's small set maps clearly to error categories: success, cancellation, invalid input, resource not found, authentication failures, and more. Every gRPC response includes a status code and an optional status message.

NOT_FOUND (5) means the requested resource or entity does not exist — for example, a user ID that was deleted or never created. UNIMPLEMENTED (12) means the method or operation itself is not supported on this server — for example, calling a beta endpoint on a stable server, or calling an RPC that was removed.

Yes, UNAVAILABLE is the primary retryable error code. It signals a transient server-side condition like an overloaded backend or a temporary network interruption. Use exponential backoff with jitter. The other commonly retryable code is RESOURCE_EXHAUSTED (8) when caused by rate limiting rather than quota exhaustion.

CANCELLED (1) means the client explicitly cancelled the RPC before it completed — for example, the user navigated away. DEADLINE_EXCEEDED (4) means the deadline set by the client (or server) elapsed before the RPC finished. Both result in termination, but DEADLINE_EXCEEDED indicates the operation was simply too slow while CANCELLED indicates intentional termination.

INTERNAL (13) is for unexpected, unrecoverable server errors — bugs, invariant violations, or cases where the server is in a state it should never be in. FAILED_PRECONDITION (9) is for expected business-logic errors where the system is in the wrong state for this operation — for example, calling Delete on a non-empty directory, or trying to resume a completed workflow.

Common mappings: OK→200, CANCELLED→499, INVALID_ARGUMENT→400, NOT_FOUND→404, ALREADY_EXISTS→409, PERMISSION_DENIED→403, UNAUTHENTICATED→401, RESOURCE_EXHAUSTED→429, INTERNAL→500, UNIMPLEMENTED→501, UNAVAILABLE→503, DEADLINE_EXCEEDED→504. These mappings are used by gRPC-HTTP/1.1 transcoding proxies like Envoy and Cloud Endpoints.