Choosing Canonical Error Codes

Status returns errors using an absl::StatusCode, which is an enumerated type indicating either no error (“OK”) or an error condition. These error codes map to the google.rpc.Code RPC error codes indicated in https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto.

This is a cheat sheet you can use to pick an appropriate error. Pick the most specific error code that applies.

Condition Code
The request succeeded OK
The request was cancelled, typically by the caller CANCELLED
The request parameters would never work INVALID_ARGUMENT
The operation did not complete within the specified deadline DEADLINE_EXCEEDED
The requested entity does not exist NOT_FOUND
The entity being created already exists ALREADY_EXISTS
The caller does not have permission to execute the operation PERMISSION_DENIED
The caller’s identity cannot be verified UNAUTHENTICATED
Some infrastructure resource is exhausted (quota, server capacity, etc) RESOURCE_EXHAUSTED
The system is not in the required state for the operation FAILED_PRECONDITION
The operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc. ABORTED
There was a transient error UNAVAILABLE
The client has iterated too far, and should stop OUT_OF_RANGE
There is no implementation for the requested operation UNIMPLEMENTED
A serious internal invariant is broken (i.e. worthy of a bug or outage report) INTERNAL
Unrecoverable data loss or corruption DATA_LOSS
There is no way to determine a more specific error code UNKNOWN

Note: Choosing between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE is subtle, especially with respect to the retry strategy the caller should use. Some guidelines that may help a service implementer:

  • Use UNAVAILABLE if the client can retry just the failing call.
  • Use ABORTED if the client should retry at a higher transaction level (such as when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence).
  • Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. For example, if an “rmdir” fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
  • Use INVALID_ARGUMENT (and not OUT_OF_RANGE) if the input value will never be accepted. OUT_OF_RANGE should be reserved for inputs that are out of range only because of the current system state.