gRPC status code lookup
Type a code or a name, such as 14, UNAVAILABLE or DeadlineExceeded, or paste a whole error message, to see what it means, what usually causes it and what to check. All seventeen codes are listed below, each with a page of its own.
Updated
All status codes
| Code | Name | Meaning | HTTP |
|---|---|---|---|
| 0 | OK | The call succeeded. It is the only status that is not an error. | 200 |
| 1 | CANCELLED | The call was cancelled, almost always by the caller. | 499 |
| 2 | UNKNOWN | An error with no better code: the server failed in a way it did not classify. | 500 |
| 3 | INVALID_ARGUMENT | The request is invalid regardless of the server's state: a bad field value, a malformed name, a missing required field. | 400 |
| 4 | DEADLINE_EXCEEDED | The deadline expired before the call finished. The server took longer than the time the client allowed. | 504 |
| 5 | NOT_FOUND | The requested entity, such as a file, row or user, does not exist. | 404 |
| 6 | ALREADY_EXISTS | The entity the client tried to create already exists. | 409 |
| 7 | PERMISSION_DENIED | The caller is identified but not allowed to do this. | 403 |
| 8 | RESOURCE_EXHAUSTED | A resource ran out: a quota, a rate limit, memory, or the maximum message size. | 429 |
| 9 | FAILED_PRECONDITION | The system is not in the state the call needs, such as deleting a directory that is not empty. | 400 |
| 10 | ABORTED | The operation was aborted, typically by a concurrency conflict such as a failed transaction or sequencer check. | 409 |
| 11 | OUT_OF_RANGE | The request went past the valid range, such as reading beyond the end of a file or a page past the last. | 400 |
| 12 | UNIMPLEMENTED | The server does not implement this method, or does not know the service at all. | 501 |
| 13 | INTERNAL | An invariant the system relies on broke. Something is seriously wrong on the server or in the transport. | 500 |
| 14 | UNAVAILABLE | The service cannot be reached right now. It is usually transient, and the most common error when a call never gets through. | 503 |
| 15 | DATA_LOSS | Data was lost or corrupted beyond recovery, such as stored data that fails its checksum. The client cannot fix it. | 500 |
| 16 | UNAUTHENTICATED | The request has no valid credentials for the operation. | 401 |
Worked example
A Go client fails with rpc error: code = DeadlineExceeded desc = context deadline exceeded. Paste the line into the lookup and it answers:
DEADLINE_EXCEEDED (4)
The deadline expired before the call finished. The server took longer than the time the client allowed.
Usual causes:
- The server was slow: a slow query, a lock, or a downstream call that took most of the budget.
- The deadline is too short for the work, often a default copied from a faster endpoint.
- The connection could not be established in time, so the call never reached the server.
- Deadline propagation: the call inherited a nearly spent deadline from an upstream request.The lookup reads Go names such as DeadlineExceeded, Python's StatusCode.DEADLINE_EXCEEDED, the canonical DEADLINE_EXCEEDED, the lowercase deadline_exceeded istek shows, and the number 4.
Which codes the library raises, and which the server does
gRPC itself only raises a few codes: CANCELLED, UNKNOWN, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED, UNIMPLEMENTED, INTERNAL, UNAVAILABLE and UNAUTHENTICATED. The rest, such as NOT_FOUND or PERMISSION_DENIED, come from the service's own code, so their exact meaning is in its documentation.
istek shows the status of every call in its status bar, and explains transport failures, such as a TLS mismatch or a refused connection, in plain words. See istek.