Task 1.14: Centralized Error Handling

Summary

Implement centralized error handling system for buylater.email with consistent error responses, proper logging, and user-friendly error pages to improve reliability and user experience.

Motivation

Following Let’s Go Chapter 3.4, we need to replace scattered error handling with a centralized system that provides consistent error responses, proper logging, and graceful error recovery throughout the application.

Acceptance Criteria

Create centralized error handling helper methods
Implement consistent HTTP error response format
Add proper error logging with context and stack traces
Create user-friendly error pages (404, 500, etc.)
Implement error recovery mechanisms
Add error categorization (client errors vs server errors)
Update all handlers to use centralized error handling
Add error monitoring and alerting preparation
Implement graceful degradation for non-critical errors

Technical Requirements

Error Handler Structure

func (app *application) serverError(w http.ResponseWriter, err error) {
    // Log error with stack trace
    // Return 500 error page
}

func (app *application) clientError(w http.ResponseWriter, status int) {
    // Log client error
    // Return appropriate error page
}

func (app *application) notFound(w http.ResponseWriter) {
    // Return 404 error page
}

Implementation Details

Create error helper methods on application struct
Implement proper error logging with context
Create HTML templates for error pages
Add error categorization and handling logic
Update all handlers to use centralized error methods
Implement consistent error response format

Dependencies

Task 1.13 completed (dependency injection for clean error handler access)

Testing Strategy

Unit Tests

Test error handler methods with various error types
Verify error logging includes proper context
Test error response formatting

Integration Tests

404 errors return proper not found page
500 errors return proper server error page
Error logging works for all error conditions

Manual Testing

Visit non-existent routes to test 404 handling
Trigger server errors to test 500 handling
Verify error pages are user-friendly and branded
Check error logs contain useful debugging information
Test error handling in all existing handlers

Definition of Done

All acceptance criteria met
All specified tests pass
Code follows project conventions (go fmt, go vet)
Consistent error handling throughout application
User-friendly error pages with proper branding
Comprehensive error logging for debugging
Human verification completed successfully
Git commit created with proper message format

Implementation Notes

Approach

Replace ad-hoc error handling with a centralized system that provides consistent, user-friendly error responses while maintaining comprehensive error logging for operations.

Key Files to Create/Modify

cmd/web/helpers.go - New file for error handling helpers
ui/html/pages/error.tmpl - Generic error page template
ui/html/pages/404.tmpl - Not found page template
cmd/web/handlers.go - Update all handlers to use centralized errors

Error Page Design

Consistent with buylater.email branding
User-friendly error messages
Helpful navigation options
No technical details exposed to users
Professional appearance

Error Categories

Client Errors (4xx): Bad requests, not found, method not allowed
Server Errors (5xx): Template errors, database errors, internal failures
Recovery: Graceful handling of non-critical errors

Potential Risks

Error handling overhead could impact performance
Over-generic error messages might reduce debugging info
Error page template failures could cause recursive errors

Success Metrics

Professional error handling system that provides excellent user experience during errors while maintaining comprehensive error logging and monitoring capabilities for operations.

Blocks: Production deployment, monitoring, and reliability improvements
Blocked by: Task 3.3 (needs dependency injection)
Related: User experience, logging, and operational monitoring

Implementation Log

Implementation details will be recorded here during development.

Final Verification

Human Tester: [Name]
Date Completed: [YYYY-MM-DD]
Verification Result: [Pass/Fail]
Notes: [Any issues found or additional observations]

task_id: “1.14” title: “Centralized Error Handling” status: “pending” priority: “high” estimated_effort: “medium” created: “2025-07-24” assigned_to: “pair” related_rfds: “RFD 004”