Centralize error responses with a typed AppError class and asyncHandler wrapper

[mikewheeleer]

Refactor error handling into a typed AppError and asyncHandler

Description

Every handler in src/index.ts hand-builds its error JSON inline — repeating the { error, message, requestId } object dozens of times for 400/404/409/503 — and re-deriving req.id via the verbose (req as Request & { id?: string }).id cast each time. This is repetitive and error-prone. This issue centralizes errors behind a typed helper without changing the wire format.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-backend only.
• Add an AppError class with status, code (error field), and message, plus factory helpers (badRequest, notFound, conflict, paused, payloadTooLarge).
• Add an asyncHandler wrapper so thrown AppErrors reach the final error handler, which renders the existing envelope (error, message, requestId, and method/path for 500).
• Add a typed req.id augmentation (an Express Request interface extension) to remove the repeated casts.
• Produce byte-for-byte identical responses for all current error cases; no route path or status code changes.

Suggested execution

• Fork the repo and create a branch
• git checkout -b refactor/api-28-app-error-helpers
• Implement changes
  • Write code in: new src/errors/AppError.ts and a src/types/express.d.ts, refactoring call sites in src/index.ts.
  • Write comprehensive tests in: new src/errors/AppError.test.ts — each factory yields the correct status/body; existing suite stays green.
  • Add documentation: document the error model in docs/errors.md.
  • Add TSDoc on AppError and the factories.
  • Validate security assumptions: error bodies still omit stack traces and internal detail.
• Test and commit

Test and commit

• Run npm run build, npm test, and npm run lint.
• Cover edge cases: every status code currently emitted (400/404/409/413/429/503/500).
• Include the full npm test output and a before/after response sample in the PR description.

Example commit message

refactor: centralize errors with typed AppError and asyncHandler

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.