# Error Handling

## Overview

The `cleveragents.core.error_handling` module provides centralized
error classification, secret redaction, and exception wrapping for
consistent CLI output and safe logging.

## Error Codes

All errors are mapped to HTTP-like numeric codes:

### Client Errors (400-range)

| Code | Name                | Mapped From                   |
|------|---------------------|-------------------------------|
| 400  | BAD_REQUEST         | BusinessRuleViolation, PlanError, DomainError |
| 401  | UNAUTHORIZED        | AuthenticationError           |
| 403  | FORBIDDEN           | AuthorizationError            |
| 404  | NOT_FOUND           | ResourceNotFoundError         |
| 409  | CONFLICT            | ResourceConflictError         |
| 422  | VALIDATION_FAILED   | ValidationError               |
| 429  | RATE_LIMITED        | RateLimitError                |

### Server Errors (500-range)

| Code | Name                | Mapped From                   |
|------|---------------------|-------------------------------|
| 500  | INTERNAL            | CleverAgentsError (catch-all) |
| 503  | SERVICE_UNAVAILABLE | ExternalServiceError          |
| 520  | PROVIDER_ERROR      | ProviderError                 |
| 521  | EXECUTION_ERROR     | ExecutionError                |
| 522  | DATABASE_ERROR      | DatabaseError                 |
| 523  | FILESYSTEM_ERROR    | FileSystemError               |
| 524  | NETWORK_ERROR       | NetworkError                  |
| 525  | CONFIGURATION_ERROR | ConfigurationError            |
| 526  | TOKEN_LIMIT         | TokenLimitExceededError        |
| 527  | MODEL_UNAVAILABLE   | ModelNotAvailableError         |
| 528  | STREAM_ERROR        | StreamRoutingError            |

## Secret Redaction

### Redacted Keys

The following keys are automatically redacted:

`api_key`, `apikey`, `auth_token`, `authorization`, `bearer`,
`client_secret`, `credentials`, `password`, `private_key`, `secret`,
`secret_key`, `token`

### Pattern-Based Redaction

String values are scanned for these patterns:

- OpenAI API keys (`sk-...`)
- JWT tokens (`eyJ...`)
- GitHub PATs (`ghp_...`, `ghs_...`)
- GitLab PATs (`glpat-...`)

### Usage

```python
from cleveragents.core.error_handling import redact_error_details

safe = redact_error_details({
    "api_key": "sk-real-secret",
    "plan_id": "01PLAN001",
})
# => {"api_key": "***REDACTED***", "plan_id": "01PLAN001"}
```

## Wrapping Unexpected Exceptions

Use `wrap_unexpected` to convert non-`CleverAgentsError` exceptions
into safe, user-facing errors:

```python
from cleveragents.core.error_handling import wrap_unexpected

try:
    risky_operation()
except Exception as exc:
    safe = wrap_unexpected(exc, context={"plan_id": plan_id})
    raise safe from exc
```

If the exception is already a `CleverAgentsError`, it is returned
unchanged with optional context merged.

## CLI Formatting

```python
from cleveragents.core.error_handling import classify_error, format_error_for_cli

info = classify_error(exc)
print(format_error_for_cli(info))
# Error [422] VALIDATION_FAILED: name is required
```

## Exception Hierarchy

```
CleverAgentsError
├── DomainError
│   ├── ValidationError
│   ├── BusinessRuleViolation
│   ├── ResourceNotFoundError
│   ├── ResourceConflictError
│   └── PlanError
├── InfrastructureError
│   ├── DatabaseError
│   ├── NetworkError
│   └── ExternalServiceError
├── ProviderError
│   ├── RateLimitError
│   ├── TokenLimitExceededError
│   └── ModelNotAvailableError
├── AuthenticationError
├── AuthorizationError
├── ConfigurationError
│   └── MissingConfigurationError
├── FileSystemError
├── ExecutionError
└── StreamRoutingError
```