gRPC
Which gRPC Status Code Should I Return?
gRPC defines 17 canonical status codes that map to common error conditions in distributed systems. Unlike HTTP, gRPC always returns HTTP 200 at the transport layer and encodes the status in trailers. This tree guides you to the right gRPC status code based on what went wrong.
Decision Steps
Did the RPC complete successfully?
Is the request message malformed, missing required fields, or contains invalid argument values?
Is the caller unauthenticated (no credentials or invalid/expired token)?
Does the caller lack permission to execute this operation?
Does the requested entity (resource, user, document) not exist?
Has the client exceeded a resource quota or rate limit?
Is the server or a downstream dependency temporarily unavailable?
Possible Outcomes
0-ok
RPC completed successfully
3-invalid-argument
Malformed or invalid request fields
16-unauthenticated
Missing or invalid credentials
7-permission-denied
Authenticated but lacks permission
5-not-found
Requested entity does not exist
8-resource-exhausted
Quota or rate limit exceeded
14-unavailable
Service temporarily unavailable
13-internal
Unexpected server-side error