</>
ProtocolCodes
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

Related Status Codes

gRPC 0 gRPC 3 gRPC 5 gRPC 7 gRPC 8 gRPC 13 gRPC 14 gRPC 16

Related Terms

Status Code Rate Limiting Authentication Timeout gRPC Streaming