fis:consistent error handling across modules

[Faith-okereke]

Linked Issue

Closes #609

---

What does this PR do?

This PR standardises error handling across the entire backend by replacing ad-hoc NestJS built-in exceptions (NotFoundException, ForbiddenException, ConflictException, etc.) with a consistent set of custom exception classes. Three new classes were added to the existing five — InvalidCredentialsException, InvalidTokenException, and RateLimitExceededException — to cover auth and rate-limiting scenarios that previously used raw HttpException. The GlobalExceptionFilter was extended with a Logger so unhandled and 5xx errors are captured with full stack traces. All 26 affected service, controller, guard, and middleware files were updated, and the exception mapping is documented in CLAUDE.md as the authoritative reference for contributors.

---

Type of change

• ✨ New feature (non-breaking change that adds functionality)
• 🐛 Bug fix (non-breaking change that fixes an issue)
• 💥 Breaking change (fix or feature that changes existing API behaviour)
• ♻️ Refactor (no functional change, no new feature)
• 🧪 Tests only (no production code changes)
• 📝 Documentation only
• 🔧 Chore (build, dependencies, CI config)

---

Pre-merge checklist (required)

Do not remove items. Unchecked items without an explanation will block merge.

Branch & metadata

• Branch name follows feature/issue-<N>-<slug> / fix/issue-<N>-<slug> convention
• Branch is up to date with the target branch (develop or main)
• All commits and the PR title follow the Conventional Commits format with issue reference

Code quality & tests

• npm run lint:ci — zero ESLint warnings
• npm run format:check — Prettier reports no changes needed
• npm run typecheck — zero TypeScript errors
• npm run test:ci — all tests pass, coverage ≥ 70%
• New service methods have corresponding .spec.ts unit tests
• New API endpoints are covered by at least one e2e test
• No existing tests were deleted (if any were, justification is provided in the PR description)

Error handling & NestJS best practices

• All new/updated DTOs use class-validator / class-transformer decorators and are wired through NestJS pipes (e.g. global ValidationPipe or explicit)
• All controller entry points validate external input at the boundary (no unvalidated raw any/unknown reaching the domain)
• Controllers/services throw appropriate NestJS HTTP exceptions (e.g. BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException) instead of generic Error
• Any new error shapes are handled by existing exception filters or the filters have been updated accordingly
• Logging goes through the shared logging abstraction (e.g. Nest Logger or central logger service) with meaningful, structured messages
• Authentication/authorization guards (e.g. AuthGuard, role/permissions guards, custom guards) are applied to all new/modified endpoints where appropriate
• If an endpoint is intentionally public, this is explicitly mentioned in the PR description with rationale

API documentation / Swagger

• Swagger / OpenAPI decorators are added or updated for all new/changed controller endpoints (including DTOs, responses, and error schemas)
• I have started the app locally and confirmed the /api (or Swagger UI) reflects new/changed endpoints correctly
• If there are no API surface changes, this is explicitly stated in the PR description

Breaking changes

• This PR does not introduce a breaking API change
• OR: this PR introduces a breaking change and it is documented below, with migration notes

---

Breaking change description (if applicable)

---

Test evidence (required)

node node_modules/jest/bin/jest.js
--testPathPattern="app.exceptions.spec|global-exception.filter.spec"
--no-coverage

Test Suites: 2 passed, 2 total
Tests: 21 passed, 21 total

Custom Exceptions
ResourceNotFoundException
✓ returns 404 with resource name only
✓ returns 404 with resource name and id
✓ accepts numeric id
ForbiddenOperationException
✓ returns 403 with default message
✓ accepts a custom message
ResourceConflictException
✓ returns 409 without field
✓ returns 409 with field
BusinessValidationException
✓ returns 422 with message
ServiceUnavailableException
✓ returns 503 with service name
InvalidCredentialsException
✓ returns 401 with default message
✓ accepts a custom message
InvalidTokenException
✓ returns 401 with default message
✓ accepts a custom message
RateLimitExceededException
✓ returns 429 without retry info
✓ includes retryAfterSeconds when provided

GlobalExceptionFilter
✓ maps HttpException to its status and message
✓ maps unknown errors to 500
✓ maps ResourceNotFoundException to 404
✓ maps ForbiddenOperationException to 403
✓ includes path and timestamp in every response
✓ handles non-Error thrown objects

Commands run locally

# Example (edit as needed)
npm run lint:ci
npm run format:check
npm run typecheck
npm run test:ci

Manual / API verification

# Example: describe manual tests, curl commands, or Postman collections used

---

Screenshots / recordings (if applicable)

[drips-wave]

@Faith-okereke Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[RUKAYAT-CODER]

Kindly resolve conflict and fix workflow.