# Status Codes and Rich Errors — gRPC

Source: https://www.skillbyai.com/en/grpc/r-status

> Choose the right code.

## A fixed set of codes

Every gRPC call ends with a **status**: a code plus a message. Common codes: `OK`, `INVALID_ARGUMENT` (bad input), `NOT_FOUND`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED` (quota or rate limit), `FAILED_PRECONDITION` (system not in the required state), `ABORTED` (concurrency conflict), `UNAVAILABLE` (transient, safe to retry), `DEADLINE_EXCEEDED`, `UNIMPLEMENTED` and `INTERNAL`. For structured details, the **richer error model** (`google.rpc.Status` with details such as `BadRequest` field violations) carries machine-readable information.

## Choosing codes

Situations and suitable status codes.

```text
email field is malformed                     -> INVALID_ARGUMENT (+ BadRequest field violation)
order id does not exist                      -> NOT_FOUND
no or invalid credentials                    -> UNAUTHENTICATED
valid user lacks permission                  -> PERMISSION_DENIED
cannot cancel an order that already shipped  -> FAILED_PRECONDITION
optimistic-lock version conflict             -> ABORTED
per-user quota exceeded                      -> RESOURCE_EXHAUSTED
dependency temporarily down                  -> UNAVAILABLE   (retryable)
unexpected bug                               -> INTERNAL      (do not leak details)
```

## Do not use UNKNOWN or INTERNAL for client mistakes

Specific codes let clients decide whether to fix the request, retry or give up.

**Quiz:** Which status code is generally safe to retry?

- [ ] NOT_FOUND
- [ ] INVALID_ARGUMENT
- [ ] PERMISSION_DENIED
- [x] UNAVAILABLE

*Answer:* UNAVAILABLE. Transient failures only.