Status Codes and Rich Errors

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.

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.

Quick check: Which status code is generally safe to retry?

• NOT_FOUND
• INVALID_ARGUMENT
• PERMISSION_DENIED
• UNAVAILABLE