API HTTP Status Codes Documentation

This document lists all HTTP status codes used in the API (excluding 200 OK responses) along with their locations in the codebase.

Total non-200 status code usages: 330 instances

Status Code Summary

Status Code	Description	Count
201	Created	2
400	Bad Request	4
401	Unauthorized	7
409	Conflict	15
422	Unprocessable Entity	56
500	Internal Server Error	246

Detailed Breakdown

201 Created (2 instances)

Used when a resource is successfully created.

• api/src/features/connector/convergence/controller/index.js:76
• api/src/shared/middleware/cache/get.js:19

400 Bad Request (4 instances)

Used for client-side errors where the request is malformed or invalid.

• api/src/features/account/member-directory/controller/index.js:27
• api/src/features/account/notifications/controller/index.js:43
• api/src/features/public/contact/controller/index.js:14
• api/src/shared/middleware/safety-training/member-check.js:35

401 Unauthorized (7 instances)

Used when authentication is required or has failed.

• api/docs/middlewares/auth.js:24
• api/docs/middlewares/auth.js:30
• api/docs/middlewares/auth.js:36
• api/src/shared/middleware/auth/routes.validate.js:100
• api/src/shared/middleware/auth/token.validate.js:10
• api/src/shared/middleware/auth/token.validate.js:15
• api/src/shared/middleware/payment/index.js:3

409 Conflict (15 instances)

Used when a request conflicts with the current state of the server.

Account Dashboard:

• api/src/features/account/dashboard/controller/index.js:16
• api/src/features/account/dashboard/controller/index.js:28

Account Profile:

• api/src/features/account/profile/controller/index.js:84
• api/src/features/account/profile/controller/index.js:150

Auth - Account Access:

• api/src/features/auth/account-access/controller/index.js:20
• api/src/features/auth/account-access/controller/index.js:32

Auth - Login:

• api/src/features/auth/login/controller/index.js:20
• api/src/features/auth/login/controller/index.js:32
• api/src/features/auth/login/controller/index.js:44
• api/src/features/auth/login/controller/index.js:56

Auth - Signup:

• api/src/features/auth/signup/controller/index.js:18
• api/src/features/auth/signup/controller/index.js:30
• api/src/features/auth/signup/controller/index.js:42
• api/src/features/auth/signup/controller/index.js:54

Auth - Email Verification:

• api/src/features/auth/verify-email/controller/index.js:16

422 Unprocessable Entity (56 instances)

Used for validation errors and business logic violations.

Account Features:

• api/src/features/account/approve-confirmations/controller/index.js:25
• api/src/features/account/approve-manually/controller/index.js:34
• api/src/features/account/change-request/controller/index.js:25
• api/src/features/account/coach-assessment/controller/index.js:25
• api/src/features/account/fees/controller/index.js:51
• api/src/features/account/fees/controller/index.js:63
• api/src/features/account/fees/controller/index.js:75
• api/src/features/account/logbook/controller/index.js:23
• api/src/features/account/logbook/controller/index.js:35
• api/src/features/account/logbook/controller/index.js:47
• api/src/features/account/logbook/controller/index.js:58
• api/src/features/account/manage-request/controller/index.js:34
• api/src/features/account/manage-request/controller/index.js:46
• api/src/features/account/manage-request/controller/index.js:58
• api/src/features/account/profile/controller/index.js:25
• api/src/features/account/profile/controller/index.js:37
• api/src/features/account/profile/controller/index.js:49
• api/src/features/account/profile/controller/index.js:61
• api/src/features/account/profile/controller/index.js:72
• api/src/features/account/profile/controller/index.js:96
• api/src/features/account/profile/controller/index.js:108
• api/src/features/account/profile/controller/index.js:120
• api/src/features/account/profile/controller/index.js:132
• api/src/features/account/profile/controller/index.js:144
• api/src/features/account/profile/controller/index.js:162
• api/src/features/account/safety-training/controller/index.js:160

Admin CMS Features:

• api/src/features/admin/cms/approval-level-increases/controller/index.js:25
• api/src/features/admin/cms/currency/controller/index.js:34
• api/src/features/admin/cms/currency/controller/index.js:46
• api/src/features/admin/cms/logbook/controller/index.js:25
• api/src/features/admin/cms/logbook/controller/index.js:37
• api/src/features/admin/cms/members/controller/index.js:25
• api/src/features/admin/cms/members/controller/index.js:37
• api/src/features/admin/cms/members/controller/index.js:49
• api/src/features/admin/cms/news/controller/index.js:34
• api/src/features/admin/cms/news/controller/index.js:46
• api/src/features/admin/cms/news/controller/index.js:58
• api/src/features/admin/cms/reference-materials/controller/index.js:34
• api/src/features/admin/cms/reference-materials/controller/index.js:46
• api/src/features/admin/cms/reference-materials/controller/index.js:58
• api/src/features/admin/cms/skills/controller/index.js:25
• api/src/features/admin/cms/tunnels/controller/index.js:34
• api/src/features/admin/cms/tunnels/controller/index.js:46
• api/src/features/admin/cms/tunnels/controller/index.js:58

Admin Dashboard:

• api/src/features/admin/dashboard/controller/index.js:28

Admin Reports:

• api/src/features/admin/reports/controller/index.js:25
• api/src/features/admin/reports/controller/index.js:37
• api/src/features/admin/reports/controller/index.js:49

Connector Features:

• api/src/features/connector/convergence/controller/index.js:14
• api/src/features/connector/convergence/controller/index.js:26
• api/src/features/connector/convergence/controller/index.js:80
• api/src/features/connector/convergence/controller/index.js:99
• api/src/features/connector/fuse-metrix/controller/index.js:16
• api/src/features/connector/fuse-metrix/controller/index.js:26
• api/src/features/connector/fuse-metrix/controller/index.js:38
• api/src/features/connector/fuse-metrix/controller/index.js:88

Middleware:

• api/src/shared/middleware/manage-request/skill-check.js:14
• api/src/shared/middleware/manage-request/skill-check.js:18
• api/src/shared/middleware/manage-request/skill-check.js:22
• api/src/shared/middleware/logbook/instructor.logbook.js:10
• api/src/shared/middleware/logbook/own.logbook.js:16
• api/src/shared/middleware/safety-training/member-check.js:44
• api/src/shared/utils/validator/index.js:10
• api/src/features/connector/convergence/middlewares/req-validate.js:48
• api/src/features/connector/fuse-metrix/middlewares/req-validate.js:48

500 Internal Server Error (246 instances)

Used for server-side errors and unexpected exceptions. This is the most commonly used error status code across the application, appearing in virtually every controller for general error handling.

Distribution by feature area:

• Account features: ~80 instances across all account-related controllers
• Admin CMS features: ~60 instances across all admin CMS controllers
• Admin reports: ~20 instances in reporting controllers
• Auth features: ~25 instances in authentication controllers
• Connector features: ~40 instances in integration controllers
• Public features: ~15 instances in public-facing controllers
• Middleware/Services: ~6 instances in shared utilities

Note: Due to the extensive usage (246 instances), individual line references are not listed here. The 500 status code appears in the catch blocks of virtually every API endpoint for general error handling.

Usage Patterns

1. Error Handling Consistency: The application follows a consistent pattern where business logic errors use 422, authentication issues use 401, conflicts use 409, and unexpected server errors use 500.

2. Authentication Security: All authentication-related endpoints properly return 401 status codes for unauthorized access attempts.

3. Validation Strategy: Input validation and business rule violations consistently return 422 status codes with descriptive error messages.

4. Resource Creation: The limited use of 201 status codes suggests most endpoints either return 200 for success or error codes for failures.

5. Comprehensive Error Handling: Every controller includes proper error handling with 500 status codes for unexpected exceptions.