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

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:

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

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

3.7 KiB Raw Blame History