structured error taxonomy and centralized error middleware for routing

[mikewheeleer]

Summary

routing handlers format errors ad hoc, so clients get inconsistent shapes and status codes. Introduce a typed domain-error taxonomy and route everything through one error middleware.

Why this matters

Inconsistent errors are hard to consume and hide bugs. A typed taxonomy + one mapping point makes responses predictable and testable.

Requirements

• Define a domain-error type with a code, HTTP status, and safe message.
• Route all routing errors through a single error middleware producing { code, message, requestId }.
• Never leak internal details or stack traces to clients.
• Remove the per-handler ad-hoc error formatting.

Technical guidance

• Map each domain error to exactly one status code in one place.
• Preserve the requestId for correlation.

Edge cases — each must have a test

• validation error -> consistent 400 shape
• not-found -> 404 shape
• conflict -> 409 shape
• unexpected error -> 500 with no leakage
• every error carries a requestId

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Localized error messages
• Client SDK error types

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.

[telemarkdigital-publisher]

I would like to work on this issue if still available.\n\nPlan:\n- Inspect the routing handlers, existing request-id middleware, and test patterns for current error shapes.\n- Introduce a typed domain-error model plus one centralized error middleware that maps stable codes/status/messages without leaking internals.\n- Replace ad-hoc routing error responses with the shared path and add unit/integration tests for validation, not-found, conflict, unexpected error, and requestId propagation.\n\nExpected verification: npm run lint, npm test, and npm run build. I will wait for maintainer/GrantFox assignment or acknowledgment before opening a PR.

[mikewheeleer]

@telemarkdigital-publisher, good luck — the routing error taxonomy and centralized middleware issue is now assigned to you. Start by reading the entire description and tracing the existing handlers and request context. The PR should provide stable typed errors, consistent status and response mapping, request-id preservation, safe handling without leaked internals, and tests for every listed failure path. Please keep the change coherent and high quality, run all required checks, and include Closes #554 in the PR. Submit it within 48 hours of assignment; otherwise I will unassign the issue for another contributor.

[telemarkdigital-publisher]

Submitted PR #558: #558

Verification completed locally:

• npm run lint (passes; existing warnings only)
• npm test -- --runInBand
• npm run build

[telemarkdigital-publisher]

Delivery tracking note: PR #558 is submitted at #558 and the PR body includes Closes #554. Local verification already completed: npm run lint, npm test -- --runInBand, and npm run build. GrantFox still shows this application as PR expected on my side, so if any maintainer/GrantFox refresh or extra link format is needed, please let me know.