feat(backend): Implement Structured Error Handling with Custom Error Classes

[devJaja]

Summary

Replace ad-hoc error handling with a structured error class hierarchy, consistent error response format, and error correlation IDs throughout the backend.

Motivation

Current error handling is inconsistent: some routes throw plain Error objects, others return inline error responses. This makes debugging and client-side error handling difficult.

Acceptance Criteria

• Base AppError class with: code, message, statusCode, details, correlationId
• Specific error classes: NotFoundError, ValidationError, AuthenticationError, RateLimitError, PaymentError
• All errors include correlation ID matching request ID
• Error response format: { error: { code, message, details, correlationId, timestamp } }
• Error handler middleware catches all AppError instances
• Unhandled errors logged with full stack trace and correlation ID
• Client receives sanitized errors (no internal details in production)
• Unit tests for error creation, serialization, and handler behavior

Files to Modify

File	Action
backend/src/errors/AppError.ts	New: base error class
backend/src/errors/NotFoundError.ts	New: 404 error
backend/src/errors/ValidationError.ts	New: 400 validation error
backend/src/errors/AuthenticationError.ts	New: 401 auth error
backend/src/errors/RateLimitError.ts	New: 429 rate limit error
backend/src/api/middleware/errorHandler.ts	Update to handle AppError instances
backend/src/api/routes/tasks.ts	Replace inline errors with AppError classes
backend/src/api/routes/agents.ts	Replace inline errors with AppError classes
backend/src/errors/AppError.test.ts	New: error class tests

How to Contribute

1. Create branch feat/structured-error-handling
2. Define error class hierarchy
3. Update error handler middleware
4. Refactor routes to use new error classes
5. Write unit tests for all error classes
6. Run npm run test && npm run lint before submitting PR

[Victorjonah-prog]

I'd like to take this on — I've reviewed the current errorHandler.ts and requestId.ts middleware; there's already a res.locals.correlationId set by requestId.ts, so I'll wire the new AppError base class (and NotFoundError/ValidationError/AuthenticationError/RateLimitError/PaymentError subclasses) to reuse that instead of introducing a second ID, and update errorHandler.ts to branch on instanceof AppError for the structured { error: { code, message, details, correlationId, timestamp } } response while keeping its existing dev-vs-production sanitization split. I'll refactor tasks.ts and agents.ts to throw the new classes in place of inline errors, add the unit tests for creation/serialization/handler behavior, and submit from feat/structured-error-handling with npm run test && npm run lint passing.

[grantfox-oss]

🦊 GrantFox — @Victorjonah-prog has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #264)
2. Your PR will be reviewed by the Epta-Node maintainers

Good luck! Track your progress on GrantFox.