<!-- source: https://deepwiki.com/qhkm/zeptoclaw/10.5-error-classification -->

# Error Classification

- .claude/settings.json
- .gitignore
- src/agent/compaction.rs
- src/error.rs
- src/kernel/provider.rs
- src/providers/error_classifier.rs
- src/providers/fallback.rs
- src/providers/mod.rs
- src/providers/registry.rs
- src/utils/sanitize.rs

## Purpose and Scope

Error Classification provides a centralized system for translating raw HTTP responses from LLM provider APIs into strongly-typed, actionable error categories defined in the `ProviderError` enum [src/error.rs:19-42]. This enables consistent error handling, intelligent retry logic via `RetryProvider` [src/providers/retry.rs:36-47], and fallback provider selection in `FallbackProvider` [src/providers/fallback.rs:154-168].

The system ensures that transient failures (like rate limits) are retried automatically while permanent failures (like authentication errors) are surfaced immediately. It also identifies specialized conditions like `ContextOverflow`, which requires agent-level intervention (compaction) rather than a simple retry [src/error.rs:69-73].

## Error Classification Architecture

The system uses a tiered approach: first classifying by HTTP status code in `parse_provider_error` [src/providers/mod.rs:92-124], then refining ambiguous results (like 400 or 5xx) using pattern matching in `classify_error_message` [src/providers/error_classifier.rs:9-136].

### Natural Language to Code Entity Space: Classification Flow

This diagram maps the conceptual flow of an error response to the specific code entities responsible for processing it.

```

```

**Sources:** [src/providers/mod.rs92-124](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L92-L124) [src/error.rs19-42](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/error.rs#L19-L42) [src/error.rs117-121](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/error.rs#L117-L121)

## HTTP Status Code Mapping

The `parse_provider_error` function [src/providers/mod.rs:92] maps standard HTTP status codes to `ProviderError` variants.

**Note:ContextOverflowis not retryable by the network layer but is recoverable by the Agent Loop through compaction[src/error.rs:69-73],[src/agent/compaction.rs:194-197].*

**Sources:** [src/providers/mod.rs92-124](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L92-L124) [src/error.rs74-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/error.rs#L74-L82) [src/agent/compaction.rs1-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/agent/compaction.rs#L1-L12)

## Pattern-Based Refinement

When status codes are ambiguous, `classify_error_message` [src/providers/error_classifier.rs:9] scans the response body for specific substrings.

**Sources:** [src/providers/error_classifier.rs9-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/error_classifier.rs#L9-L136)

## Error Types and Retry Semantics

The `ProviderError` enum defines the semantics for how the system should react to a failure.

### Retryable vs Non-Retryable Errors

The `is_retryable()` method [src/error.rs:74] determines if a request should be attempted again by a generic retry layer (e.g., `RetryProvider`).

- Retryable ( true ): RateLimit , ServerError , Timeout , Overloaded [src/error.rs:77-80] .
- Non-Retryable ( false ): Auth , Billing , InvalidRequest , ModelNotFound , Format , ContextOverflow [src/error.rs:89-96] .

### Fallback Logic

The `should_fallback()` method [src/error.rs:88] determines if an error should trigger a switch to a secondary provider in a `FallbackProvider` [src/providers/fallback.rs:154].

```

```

**Sources:** [src/error.rs62-97](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/error.rs#L62-L97) [src/providers/retry.rs36-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/retry.rs#L36-L47)

## Decorator Chain Flow

Error classification drives the behavior of provider decorators assembled in `build_provider_chain` [src/kernel/provider.rs:23-30].

1. RetryProvider : Intercepts ZeptoError . It calls is_retryable() on the inner error [src/error.rs:74] . If true, it performs exponential backoff [src/providers/retry.rs:36] .
2. FallbackProvider : If the primary provider fails with an error where should_fallback() is true [src/error.rs:88] , it routes the request to the next provider in the configured chain [src/providers/fallback.rs:154] . It also maintains a CircuitBreaker [src/providers/fallback.rs:60] to skip unhealthy providers.
3. QuotaProvider : Tracks usage and may preemptively return ProviderError::RateLimit if local quotas are exceeded [src/providers/quota.rs:70] .

### Code Entity Space: Decorator Interaction

```

```

**Sources:** [src/kernel/provider.rs23-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L23-L30) [src/providers/mod.rs92-124](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L92-L124) [src/error.rs74-97](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/error.rs#L74-L97) [src/providers/fallback.rs60-136](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/fallback.rs#L60-L136)
