Error Migration Guide¶
This document describes the typed error hierarchy in Primr v1.5.0.
Overview¶
Primr v1.5.0 uses a unified typed error hierarchy that provides:
- Automatic retry classification via recoverable property
- Structured error context with correlation IDs
- Clear categorization (ai, scraping, search, configuration, validation, etc.)
- Backward-compatible aliases for existing code
Error Classes¶
| Error Class | Category | Recoverable | Use Case |
|---|---|---|---|
PrimrError |
general | No | Base class for all errors |
TransientError |
transient | Yes | Base for retryable errors |
PermanentError |
permanent | No | Base for non-retryable errors |
AIError |
ai | Yes | AI/LLM operation failures |
ScrapingError |
scraping | Yes | Web scraping failures |
SearchError |
search | Yes | Search API failures |
RateLimitError |
rate_limit | Yes | API rate limit exceeded |
ConfigurationError |
configuration | No | Invalid/missing configuration |
ValidationError |
validation | No | Input validation failures |
OutputError |
output | No | Report generation failures |
NetworkError |
network | Yes | Network connectivity issues |
Usage Examples¶
Basic Error Handling¶
from primr.utils.errors import AIError, ScrapingError, ConfigurationError
try:
result = await api_call()
except AIError as e:
if e.recoverable:
# Safe to retry
await asyncio.sleep(e.retry_after or 1.0)
result = await api_call()
else:
raise
except ConfigurationError as e:
# Not recoverable - fix configuration
print(f"Configuration error: {e.message}")
print(f"Guidance: {e.guidance}")
Error with Context¶
from primr.utils.errors import ScrapingError
# Create error with context
error = ScrapingError(
message="Failed to scrape page",
url="https://example.com",
status_code=403,
tier="playwright",
cause=original_exception
)
# Access attributes
print(error.url) # "https://example.com"
print(error.status_code) # 403
print(error.recoverable) # True
print(error.category) # "scraping"
# User-friendly output
print(error.user_message()) # Message + guidance
print(error.debug_message()) # Full details including cause
Rate Limit Handling¶
from primr.utils.errors import RateLimitError
try:
response = api.call()
except RateLimitError as e:
# retry_after is automatically set
await asyncio.sleep(e.retry_after)
response = api.call()
Error Formatting Utilities¶
from primr.utils.errors import (
format_error_for_user,
get_error_guidance,
is_recoverable_error,
)
# Format for display
user_msg = format_error_for_user(error, verbose=False)
debug_msg = format_error_for_user(error, verbose=True)
# Get guidance
guidance = get_error_guidance(error)
# Check recoverability
if is_recoverable_error(error):
# Safe to retry
pass
Typed Error Hierarchy¶
All errors inherit from PrimrError, which provides:
message: Human-readable error descriptioncategory: Error category for classificationrecoverable: Whether the error can be retriedretry_after: Suggested delay before retry (seconds)correlation_id: Unique ID for tracingtimestamp: When the error occurredcause: The underlying exceptioncontext: Additional context dataguidance: User-friendly resolution guidance
Methods:
- user_message(): Clean message for users (no stack traces)
- debug_message(): Detailed message for debugging
- to_dict(): JSON-serializable dictionary
Backward Compatibility¶
The following aliases are provided for backward compatibility:
# These all work and point to the typed error classes
from primr.utils.errors import (
ResearchError, # -> PrimrError
AIError, # -> PrimrAIError
ScrapingError, # -> PrimrScrapingError
SearchError, # -> PrimrSearchError
ConfigurationError, # -> PrimrConfigurationError
ValidationError, # -> PrimrValidationError
OutputError, # -> PrimrOutputError
RateLimitError, # -> TypedRateLimitError (with wrapper)
NetworkError, # -> TypedNetworkError
)
Existing code using these names will continue to work without changes.