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

> Explore the 17 canonical Abseil StatusCode error codes in absl status status.h for standardized C++ error handling. Understand kOk to kDataLoss for robust applications.

- Repository: [Abseil/abseil-cpp](https://github.com/abseil/abseil-cpp)
- Tags: api-reference
- Published: 2026-07-12

---

**Abseil defines 17 canonical `StatusCode` error codes in [`absl/status/status.h`](https://github.com/abseil/abseil-cpp/blob/main/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`](https://github.com/abseil/abseil-cpp/blob/main/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`](https://github.com/abseil/abseil-cpp/blob/main/absl/status/status.h)**. This header also declares the `absl::Status` class and factory functions that construct status objects using these codes.

```cpp
// 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`](https://github.com/abseil/abseil-cpp/blob/main/absl/status/status.h) and improve code readability.

```cpp
#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`.

```cpp
#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`](https://github.com/abseil/abseil-cpp/blob/main/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`](https://github.com/abseil/abseil-cpp/blob/main/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`](https://github.com/abseil/abseil-cpp/blob/main/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`](https://github.com/abseil/abseil-cpp/blob/main/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`](https://github.com/abseil/abseil-cpp/blob/main/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.