Error Handling

Error Handling Skill

Purpose

Standards for consistent error handling across frontend and backend layers (examples in React + Python).

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 SCREAMINGSNAKECASE
• 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: komluk
• Source: komluk/scaffolding
• License: MIT

Install and usage instructions live in the source repository linked above.