An enumerated type indicating either no error ("OK") or an error condition.

Synopsis

Declared in <absl/status/status.h>

enum class StatusCode : int;

Description

In most cases, an absl::Status indicates a recoverable error, and the purpose of signalling an error is to indicate what action to take in response to that error. These error codes map to the proto RPC error codes indicated in https://cloud.google.com/apis/design/errors.

The errors listed below are the canonical errors associated with absl::Status and are used throughout the codebase. As a result, these error codes are somewhat generic.

In general, try to return the most specific error that applies if more than one error may pertain. For example, prefer kOutOfRange over kFailedPrecondition if both codes apply. Similarly prefer kNotFound or kAlreadyExists over kFailedPrecondition.

Because these errors may cross RPC boundaries, these codes are tied to the google.rpc.Code definitions within https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto The string value of these RPC codes is denoted within each enum below.

If your error handling code requires more context, you can attach payloads to your status. See absl::Status::SetPayload() and absl::Status::GetPayload() below.

Members

Name

Description

kOk

(gRPC code "OK") does not indicate an error; this value is returned on success. It is typical to check for this value before proceeding on any given call across an API or RPC boundary. To check this value, use the absl::Status::ok() member function rather than inspecting the raw code.

kCancelled

(gRPC code "CANCELLED") indicates the operation was cancelled, typically by the caller.

kUnknown

(gRPC code "UNKNOWN") indicates an unknown error occurred. In general, more specific errors should be raised, if possible. Errors raised by APIs that do not return enough error information may be converted to this error.

kInvalidArgument

(gRPC code "INVALID_ARGUMENT") indicates the caller specified an invalid argument, such as a malformed filename. Note that use of such errors should be narrowly limited to indicate the invalid nature of the arguments themselves. Errors with validly formed arguments that may cause errors with the state of the receiving system should be denoted with kFailedPrecondition instead.

kDeadlineExceeded

(gRPC code "DEADLINE_EXCEEDED") indicates a deadline expired before the operation could complete. For operations that may change state within a system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.

kNotFound

(gRPC code "NOT_FOUND") indicates some requested entity (such as a file or directory) was not found.

kAlreadyExists

(gRPC code "ALREADY_EXISTS") indicates that the entity a caller attempted to create (such as a file or directory) is already present.

kPermissionDenied

(gRPC code "PERMISSION_DENIED") indicates that the caller does not have permission to execute the specified operation. Note that this error is different than an error due to an _un_authenticated user. This error code does not imply the request is valid or the requested entity exists or satisfies any other pre‐conditions.

kResourceExhausted

(gRPC code "RESOURCE_EXHAUSTED") indicates some resource has been exhausted, perhaps a per‐user quota, or perhaps the entire file system is out of space.

kFailedPrecondition

(gRPC code "FAILED_PRECONDITION") indicates that the operation was rejected because the system is not in a state required for the operation's execution. For example, a directory to be deleted may be non‐empty, an "rmdir" operation is applied to a non‐directory, etc.

kAborted

(gRPC code "ABORTED") indicates the operation was aborted, typically due to a concurrency issue such as a sequencer check failure or a failed transaction.

kOutOfRange

(gRPC code "OUT_OF_RANGE") indicates the operation was attempted past the valid range, such as seeking or reading past an end‐of‐file.

kUnimplemented

(gRPC code "UNIMPLEMENTED") indicates the operation is not implemented or supported in this service. In this case, the operation should not be re‐attempted.

kInternal

(gRPC code "INTERNAL") indicates an internal error has occurred and some invariants expected by the underlying system have not been satisfied. This error code is reserved for serious errors.

kUnavailable

(gRPC code "UNAVAILABLE") indicates the service is currently unavailable and that this is most likely a transient condition. An error such as this can be corrected by retrying with a backoff scheme. Note that it is not always safe to retry non‐idempotent operations.

kDataLoss

(gRPC code "DATA_LOSS") indicates that unrecoverable data loss or corruption has occurred. As this error is serious, proper alerting should be attached to errors such as this.

kUnauthenticated

(gRPC code "UNAUTHENTICATED") indicates that the request does not have valid authentication credentials for the operation. Correct the authentication and try again.

kDoNotUseReservedForFutureExpansionUseDefaultInSwitchInstead_

Reserved for future expansion; do not use.

Non-Member Functions

Name

Description

ErrnoToStatusCode

Returns the StatusCode for error_number, which should be an errno value.

StatusCodeToString

Returns the name for the status code, or "" if it is an unknown value.

StatusCodeToStringView

Same as StatusCodeToString(), but returns a string_view.

Created with MrDocs