Canonical Abseil StatusCode Error Codes: Complete Reference for abseil-cpp

Abseil defines 17 canonical StatusCode error codes in absl/status/status.h that provide a standardized vocabulary for error handling across C++ applications, ranging from kOk for success to kDataLoss for unrecoverable corruption.

The abseil-cpp repository implements a robust error-handling model centered on the absl::Status class. At the heart of this system lies the StatusCode enumeration, which offers a fixed, language-agnostic set of error codes derived from Google's canonical RPC status conventions. These codes ensure consistent error semantics across libraries and services.

The Complete List of Canonical StatusCode Values

The absl::StatusCode enum in absl/status/status.h defines the following canonical error codes. These values are intentionally stable and mirror the canonical Google RPC status codes:

• kOk – The operation completed successfully.
• kCancelled – The operation was cancelled, typically by the caller.
• kUnknown – An unknown error not covered by other codes.
• kInvalidArgument – The caller supplied invalid arguments.
• kDeadlineExceeded – The operation timed out before completing.
• kNotFound – The requested entity does not exist.
• kAlreadyExists – An attempt was made to create an entity that already exists.
• kPermissionDenied – The caller lacks necessary permissions.
• kUnauthenticated – authentication credentials are missing or invalid.
• kResourceExhausted – System resources have been exhausted (e.g., quotas).
• kFailedPrecondition – The system is not in a state required for the operation.
• kAborted – The operation was aborted, typically due to a concurrency conflict.
• kOutOfRange – An index or offset is outside the valid range.
• kUnimplemented – The operation is not implemented or supported.
• kInternal – An internal error indicating a bug in the implementation.
• kUnavailable – The service is currently unavailable.
• kDataLoss – Irrecoverable data loss or corruption has occurred.

These codes provide a canonical vocabulary that prevents error handling fragmentation across codebases.

Where StatusCode Is Defined in abseil-cpp

The canonical error codes are defined in the absl::StatusCode enumeration within absl/status/status.h. This header also declares the absl::Status class and factory functions that construct status objects using these codes.

// From absl/status/status.h
enum class StatusCode {
  kOk = 0,
  kCancelled = 1,
  kUnknown = 2,
  kInvalidArgument = 3,
  kDeadlineExceeded = 4,
  kNotFound = 5,
  kAlreadyExists = 6,
  kPermissionDenied = 7,
  kUnauthenticated = 16,
  kResourceExhausted = 8,
  kFailedPrecondition = 9,
  kAborted = 10,
  kOutOfRange = 11,
  kUnimplemented = 12,
  kInternal = 13,
  kUnavailable = 14,
  kDataLoss = 15,
};

The integer values are intentionally stable to ensure binary compatibility across versions of the abseil-cpp library.

Constructing Status Objects with Canonical Codes

While you can construct an absl::Status directly with a code and message, abseil-cpp provides convenience factory functions that map to canonical StatusCode values. These helpers reside in absl/status/status.h and improve code readability.

#include "absl/status/status.h"
#include "absl/strings/str_cat.h"

// Using canonical constructor helpers
absl::Status success = absl::OkStatus();                          // kOk
absl::Status not_found = absl::NotFoundError("File missing");     // kNotFound
absl::Status invalid = absl::InvalidArgumentError("Bad input");     // kInvalidArgument
absl::Status denied = absl::PermissionDeniedError("Access denied"); // kPermissionDenied

Each factory function creates an absl::Status instance with the corresponding canonical StatusCode and the provided message string.

Working with StatusCode in Practice

Production code typically checks StatusCode values to determine error handling paths. The absl::Status class provides the code() accessor to retrieve the canonical code, and the ok() method to check for kOk.

#include "absl/status/status.h"
#include <iostream>

absl::Status ReadConfig(const std::string& path) {
  if (path.empty()) {
    return absl::InvalidArgumentError("Path cannot be empty");
  }
  // Simulate file check
  return absl::NotFoundError(absl::StrCat("File not found: ", path));
}

void Process() {
  absl::Status s = ReadConfig("settings.txt");
  
  if (!s.ok()) {
    // Check specific canonical codes
    if (s.code() == absl::StatusCode::kNotFound) {
      std::cerr << "Config missing, using defaults\n";
    } else if (s.code() == absl::StatusCode::kInvalidArgument) {
      std::cerr << "Invalid path provided\n";
    }
  }
}

When propagating errors, preserve the original StatusCode to maintain semantic meaning up the call stack.

Related Abseil Status Components

The canonical StatusCode enumeration integrates with several other abseil-cpp components:

• absl/status/statusor.h – Provides absl::StatusOr<T>, a variant type that holds either a value or a Status using the same canonical error codes.
• absl/status/status_macros.h – Contains macros like ABSL_RETURN_IF_ERROR and ABSL_ASSIGN_OR_RETURN that leverage canonical codes for early returns.
• absl/status/status_matchers.h – Offers GoogleTest matchers for asserting specific StatusCode values in unit tests.

These components form a cohesive error-handling ecosystem built upon the canonical error code vocabulary.

Summary

• Abseil defines 17 canonical error codes in absl/status/status.h ranging from kOk to kDataLoss.
• The StatusCode enum values are intentionally stable and match Google's canonical RPC status conventions.
• Factory functions like absl::NotFoundError() and absl::OkStatus() simplify construction of status objects with canonical codes.
• Check codes using status.code() or status.ok() to implement error-specific handling logic.
• The canonical codes integrate with StatusOr, status macros, and test matchers for complete error handling coverage.

Frequently Asked Questions

What is the difference between kUnknown and kInternal StatusCode values?

kUnknown serves as a catch-all for errors that do not fit other categories, often used when the error source cannot be determined. kInternal specifically indicates an internal invariant has been broken or a bug exists in the implementation itself. According to the abseil-cpp source code, kInternal signals that something has gone wrong within the service logic, while kUnknown suggests an unexpected condition where the error type is truly unspecified.

How do I convert a StatusCode to a human-readable string?

Call the absl::StatusCodeToString() function declared in absl/status/status.h. This function maps each canonical StatusCode to its textual representation (e.g., kNotFound becomes "NOT_FOUND"). This is useful for logging and debugging when you need to display the specific error code encountered.

Can I add custom error codes to the Abseil StatusCode enum?

No, the StatusCode enumeration is intentionally closed and canonical. The abseil-cpp design philosophy encourages using the existing 17 codes with descriptive messages rather than extending the enum. If you need application-specific error categorization, wrap absl::Status in your own type or use the kUnknown or kInternal codes with detailed message strings.

What is the relationship between StatusCode and absl::StatusOr?

absl::StatusOr<T> uses the same canonical StatusCode values as absl::Status. A StatusOr object either contains a value of type T or an absl::Status with one of the canonical error codes. When a StatusOr lacks a value, you access the error code via .status().code(), allowing seamless integration between the error code enumeration and value-or-error return types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}