gRPC vs HTTP Status Codes
gRPC uses its own status code system (0-16) instead of HTTP codes. While gRPC runs on HTTP/2, gRPC status codes are transmitted via the grpc-status trailer, not the HTTP status.
The 17 gRPC Status Codes
Success
- 0 OK — Everything worked.
Client Errors
- 3 INVALID_ARGUMENT — Client sent bad data (like HTTP 400)
- 5 NOT_FOUND — Resource doesn't exist (like HTTP 404)
- 6 ALREADY_EXISTS — Conflict (like HTTP 409)
- 7 PERMISSION_DENIED — Insufficient permissions (like HTTP 403)
- 16 UNAUTHENTICATED — No valid credentials (like HTTP 401)
- 9 FAILED_PRECONDITION — System not in required state
- 11 OUT_OF_RANGE — Value out of valid range
Server Errors
- 2 UNKNOWN — Unknown error (like HTTP 500)
- 13 INTERNAL — Internal server error
- 14 UNAVAILABLE — Service temporarily unavailable (like HTTP 503)
- 4 DEADLINE_EXCEEDED — Timeout (like HTTP 504)
- 8 RESOURCE_EXHAUSTED — Rate limited (like HTTP 429)
- 12 UNIMPLEMENTED — Method not implemented (like HTTP 501)
Special
- 1 CANCELLED — Client cancelled the request
- 10 ABORTED — Concurrency conflict, retry may succeed
- 15 DATA_LOSS — Unrecoverable data loss
Best Practice
Use the most specific code possible. For validation errors, use INVALID_ARGUMENT with a detailed error message. Include google.rpc.Status details for structured error information.