2.3: Standardized API Error Handling

[steilerDev]

User Story

As a developer, I want a standardized error handling mechanism for all API endpoints, so that clients receive consistent, machine-readable error responses regardless of which endpoint they call.

Parent Epic

EPIC-02: Application Shell & Infrastructure (#2)

Priority

Must Have

Dependencies

None

Acceptance Criteria

• 1. All API error responses follow the standard shape: { "error": { "code": "MACHINE_READABLE_CODE", "message": "Human-readable", "details": {} } }
• 2. A Fastify error handler plugin catches all thrown errors and formats them into the standard shape
• 3. Validation errors (from Fastify schema validation) return 400 with VALIDATION_ERROR code and include field-level details
• 4. Unhandled errors return 500 with INTERNAL_ERROR code and do NOT leak stack traces or internal details in production
• 5. Standard error codes exist for: NOT_FOUND (404), UNAUTHORIZED (401), FORBIDDEN (403), CONFLICT (409), VALIDATION_ERROR (400)
• 6. A helper function or class is available for routes to throw typed errors (e.g., throw new AppError('NOT_FOUND', 'Work item not found'))
• 7. Error responses include the correct HTTP status code

Notes

• The error shape is defined in CLAUDE.md under API Conventions
• This is a cross-cutting concern that all downstream feature epics rely on for consistent API behavior
• The error codes and HTTP status mapping should be defined in the shared package for reuse by the API client (Story 2.6)

[steilerDev]

[product-owner] Story Readiness Assessment

Status: ✅ READY FOR DEVELOPMENT

This story has been reviewed and is ready for handoff to the product-architect for technical design.

Acceptance Criteria Quality: 10/10

• 7 testable, unambiguous acceptance criteria
• Clear error response format specification
• Comprehensive HTTP status code mapping
• Developer ergonomics (helper function/class requirement)
• Production safety (no stack trace leakage)

Dependencies

• ✅ No blockers — can start immediately
• ✅ Story 2.1: Database Plugin & Connection Management #24 (Database Plugin) is complete

Requirements Coverage

• Implements API Conventions documented in CLAUDE.md
• Aligns with Section 3.2 (Technical Requirements) and 3.4 (Usability)
• Enables all downstream feature epics (cross-cutting concern)

Parallelization

This story can be developed in parallel with Story #28 (User Schema) — no file conflicts or logical dependencies.

Next Steps

1. product-architect reviews error handling strategy and documents error code registry pattern
2. backend-developer implements error handler plugin and helper types
3. Separate PR created with Fixes #26 in commit message

Estimated Effort

1 day implementation + 0.5 day testing

[github-actions]

🎉 This issue has been resolved in version 1.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀