error-handling

Error Handling Skill

Purpose

Standards for consistent error handling across frontend and Python backend.

Auto-Invoke Triggers

• Implementing exception handling
• Creating custom exceptions
• Handling API errors
• Implementing retry logic
• Designing user-facing error messages

---

Error Categories

Category	HTTP Code	User Action	Log Level
Validation	400	Show field errors	WARN
Authentication	401	Redirect to login	WARN
Authorization	403	Show permission denied	WARN
NotFound	404	Show not found message	INFO
Conflict	409	Show conflict details	WARN
RateLimit	429	Show retry-after	WARN
ExternalService	502	Show fallback/retry option	ERROR
Internal	500	Show generic error	ERROR
Critical	500	Show maintenance page	CRITICAL

---

Exception Hierarchy Design

Principles

• Create base AppException class for all application errors
• Extend with specific exception types per category
• Include: code, message, status code, details (optional)
• Never expose internal details to clients

Required Exception Types

1. ValidationException - Invalid input data
2. AuthenticationException - Auth token invalid/expired
3. AuthorizationException - User lacks permission
4. NotFoundException - Resource doesn't exist
5. ConflictException - Resource state conflict
6. RateLimitException - Too many requests
7. ExternalServiceException - Third-party failure

---

Error Response Format

Standard Structure

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "details": { "field": ["error1", "error2"] },
  "correlationId": "abc-123"
}

Error Codes Convention

• Use SCREAMING_SNAKE_CASE
• Be specific: USER_NOT_FOUND not NOT_FOUND
• Group by domain: AUTH_TOKEN_EXPIRED, AUTH_INVALID_CREDENTIALS

---

Frontend Error Handling

Principles

• Catch errors at API client level
• Transform to typed error objects
• Display user-friendly messages
• Log for debugging (not in production)

Error Boundary Rules

• Wrap major UI sections
• Provide fallback UI
• Log errors to monitoring service
• Allow recovery when possible

User Message Guidelines

• Be helpful, not technical
• Suggest actions user can take
• Don't blame the user
• Include support contact for critical errors

---

Backend Error Handling

Global Exception Handler

• Catch all unhandled exceptions
• Log with full context (path, method, user, correlation ID)
• Return standardized error response
• Never return stack traces in production

Exception Handling Rules

• Throw specific exceptions, catch specific exceptions
• Don't catch exceptions you can't handle
• Always re-throw or wrap caught exceptions
• Log at the boundary, not deep in code

What to Log

• Error type and message
• Request path and method
• User ID (if authenticated)
• Correlation ID
• Stack trace (for unexpected errors)

What NOT to Log

• Passwords or tokens
• Full request/response bodies with PII
• Credit card numbers
• Personal data (GDPR)

---

Retry Logic Standards

When to Retry

• Network timeouts
• 5xx server errors (external services)
• Rate limit (with backoff)
• Connection refused

When NOT to Retry

• 4xx client errors (except 429)
• Validation errors
• Authentication errors
• Non-idempotent operations (without idempotency key)

Retry Configuration

• Max attempts: 3
• Initial delay: 1 second
• Backoff multiplier: 2 (exponential)
• Max delay: 30 seconds
• Add jitter to prevent thundering herd

---

Circuit Breaker Pattern

Configuration

• Failure threshold: 5 failures
• Recovery timeout: 30 seconds
• Half-open max requests: 3

States

1. Closed - Normal operation, requests pass through
2. Open - Failures exceeded threshold, requests fail fast
3. Half-Open - Testing if service recovered

---

Best Practices

DO

• Use specific exception types
• Include correlation IDs in all errors
• Log errors with context
• Return user-friendly messages
• Implement retry for transient failures
• Use circuit breaker for external services

DON'T

• Catch generic Exception without re-throwing
• Log sensitive data
• Return stack traces to clients
• Use exceptions for control flow
• Ignore errors silently
• Retry non-idempotent operations blindly

---

Quality Checklist

• All API endpoints return consistent error format
• Custom exceptions extend base exception class
• Global exception handler catches all unhandled exceptions
• Errors logged with appropriate level and context
• User messages helpful but don't leak internals
• Retry logic for external service calls
• Circuit breaker for cascading failure protection
• Correlation IDs tracked through entire request