forked from HAL9000/cleveragents-core
CoreRasurae
126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
# 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
|
|
```
|