Error Handling

Error Handling Rules

1. Exception Hierarchy

Business vs System Exceptions

Error Classification

2. Error Response Format

Standard JSON Structure

{
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "User not found: 42",
    "details": [
      {
        "field": "userId",
        "message": "No user exists with the given ID"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:45.123Z",
    "requestId": "abc-123-def"
  }
}

Response Format Rules

• Use a consistent error envelope across all endpoints
• Include a machine-readable error code (not just HTTP status)
• Include a human-readable message for debugging
• Include field-level details for validation errors
• Include requestId/traceId for correlation

3. Exception Handling Principles

Do

• Catch at the appropriate layer (controller for HTTP, service for business logic)
• Always include context in exception messages (entity name, ID, field)
• Log stack traces for system exceptions
• Use error code enums for consistent codes across the application
• Include traceId in error responses for debugging

Do Not

• Catch exceptions broadly in service/repository layers
• Expose internal details (stack traces, SQL, class names) in API responses
• Use exceptions for flow control (e.g., throwing NotFoundException to check existence)
• Swallow exceptions silently (empty catch blocks)
• Log sensitive data in exception messages (passwords, tokens, PII)

4. Layer-Specific Guidelines

Controller Layer

• Do not handle exceptions directly — delegate to a centralized exception handler
• Validate request inputs at the API boundary before passing to service layer

Service Layer

• Throw business exception subtypes for business rule violations
• Wrap external API failures in domain-specific exceptions
• Use explicit try-catch only for recoverable operations

Repository / Data Layer

• Let data access exceptions propagate to the service layer
• Do not catch data access exceptions unless specific recovery logic exists

5. External API Error Handling

Principles

• Never let raw HTTP client exceptions propagate to callers
• Wrap in domain-specific exceptions (e.g., PaymentApiException)
• Log response status and body on errors (but mask sensitive data)
• Distinguish between retryable (network, 503) and non-retryable (400, 404) errors

Error Wrapping Strategy

6. Anti-Patterns

• Catching generic Exception in every method
• Returning error details in success response fields
• Using HTTP 200 for all responses with error codes in body
• Inconsistent error response formats across endpoints
• Missing error codes (only HTTP status, no application code)
• Logging errors without stack traces
• Retrying on non-idempotent failures without safeguards
• Pokemon Exception Handling: Catching all exceptions with a generic catch-all. Use specific exception types instead
• Error Swallowing: Empty catch blocks make debugging impossible. Always log or propagate errors
• Exceptions as Flow Control: Using exceptions for normal program flow degrades performance and readability

Additional References

• For standardized error response formats, RFC 7807 Problem Details, and error code design, see references/response-schema.md
• Microsoft Error Handling Best Practices - .NET exception handling best practices
• Effective Java - Exceptions - Java exception handling guide
• For Spring Boot implementation patterns (@ControllerAdvice, ErrorCode enum), see spring-framework skill — references/error-handling.md