gRPC Status Codes
All 17 gRPC status codes from OK to UNAUTHENTICATED with their numbers, the HTTP status they map to, what each means and when a client should retry.
Free · No sign-up · Your inputs stay in your browser
Reference
gRPC status codes
| Code | Name | HTTP | Meaning |
|---|---|---|---|
| 0 | OK | 200 | Success. |
| 1 | CANCELLED | 499 | The caller cancelled, usually a client timeout or a closed connection. |
| 2 | UNKNOWN | 500 | An error with no better code; often an unhandled exception. |
| 3 | INVALID_ARGUMENT | 400 | The request is wrong regardless of server state. Do not retry. |
| 4 | DEADLINE_EXCEEDED | 504 | The deadline passed; the operation may still have completed. |
| 5 | NOT_FOUND | 404 | |
| 6 | ALREADY_EXISTS | 409 | |
| 7 | PERMISSION_DENIED | 403 | Authenticated but not allowed. |
| 8 | RESOURCE_EXHAUSTED | 429 | Quota or rate limit, or out of memory. Retry with backoff. |
| 9 | FAILED_PRECONDITION | 400 | The system is not in a state for this (a directory not empty). Fix state, then retry. |
| 10 | ABORTED | 409 | Concurrency conflict such as a transaction abort; retry the whole sequence. |
| 11 | OUT_OF_RANGE | 400 | Past the valid range, such as reading beyond end of file. |
| 12 | UNIMPLEMENTED | 501 | Method not implemented or not enabled. |
| 13 | INTERNAL | 500 | An invariant broke: a serious server-side bug. |
| 14 | UNAVAILABLE | 503 | Transient; the one code that is generally safe to retry with backoff. |
| 15 | DATA_LOSS | 500 | Unrecoverable data loss or corruption. |
| 16 | UNAUTHENTICATED | 401 | No valid credentials. |
From grpc/doc/statuscodes.md; the HTTP column is the mapping gRPC-Gateway and Google's API design guide use. Choose FAILED_PRECONDITION versus ABORTED versus UNAVAILABLE by what the client should do next: fix state, retry the sequence, or retry the call.
About this tool
Method, assumptions, practical next steps, and limits.
Choosing the right code
The gRPC documentation's rule of thumb: use UNAVAILABLE if the client can retry just the failing call, ABORTED if it should retry at a higher level such as restarting a transaction, and FAILED_PRECONDITION if it should not retry until the system state is fixed. The codes are defined in gRPC's status codes guide.
Errors from the transport
Some codes are produced by the gRPC library rather than your handler: DEADLINE_EXCEEDED when a deadline passes, UNAVAILABLE when a connection fails, CANCELLED when the client goes away.