API Response Standardization | WyzQuests Documentation

Feature Owner: scorevi (Sean Patrick Caintic)
Module: System Config
Priority: P0
Sprint #12: Fully Implemented
Date: 2026-06-29

EXECUTIVE SUMMARY

What is this feature?
A centralized ApiResponseHelper utility class and ApiErrorCode enum that enforces a consistent JSON response shape across all API routes. Every route handler (Server Actions / Route Handlers) must return { success, data, error } shaped responses.

Why does it matter?
Without standardization, every route defines its own response format, making frontend error handling brittle and inconsistent. Developers must check for different error shapes per endpoint, and there is no unified way to display validation errors or server failures.

What's the MVP scope?
Implemented in lib/api/response.ts. A reusable ApiResponseHelper class with 14 static methods and 10 error codes. Used by select routes; some legacy routes (e.g., suspend-user) still mix raw NextResponse.json() calls.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Each API route returns inconsistent response shapes. One route returns { error: "msg" }, another returns { success: false, message: "msg" }. The frontend has scattered, duplicated error-parsing logic.

Pain Point

Emotional: Frustration when debugging API failures — every endpoint behaves differently.
Functional: Frontend error handling is error-prone; consumers must write bespoke parsers per endpoint.
Business Impact: Increased bug rate, slower development velocity, inconsistent user-facing error messages.

Future State (With Feature)

All API routes return exactly { success: boolean, message?: string, data: T | null, error: { code, message, details? } | null }. The frontend has a single, predictable contract.

Marketing Hook

"One response shape. Zero guesswork. Every API route speaks the same language."

2. 4D FRAMEWORK MAPPING

Diagnose

N/A — infrastructure concern.

Design

N/A — infrastructure concern.

Develop

Developers use ApiResponseHelper.success(), .error(), .validationError(), .notFound(), etc. instead of raw NextResponse.json().

Deliver

N/A — infrastructure concern, but enables consistent SCORM/xAPI export responses.

3. USER FLOWS

Entry Point

Any server-side API route handler or Server Action.

Success Criteria

Every API response in the codebase uses ApiResponseHelper static methods and returns standardized JSON.

Main Flow (Happy Path)

Route handler processes request and validates input with Zod.
On success: calls ApiResponseHelper.success(data, message?, status?).
Frontend receives { success: true, data: T, error: null }.

Edge Cases

Zod validation failure: ApiResponseHelper.validationError(message, zodErrorDetails) → 400.
Auth failure: ApiResponseHelper.unauthorized(message) → 401 or .forbidden(message) → 403.
Resource not found: ApiResponseHelper.notFound(message) → 404.
Internal exception: ApiResponseHelper.handleError(error) or .internalError(...) → 500, logs stack trace server-side.
AI content violation: ApiResponseHelper.contentPolicyViolation(...) → 422.
AI rate/token limit: ApiResponseHelper.tokenLimitExceeded(...) → 429.

Decision Points

IF the error is a known, handled case → use the specific static method (.badRequest(), .forbidden(), etc.).
ELSE (unknown error) → use .handleError(error) to log and return 500.

4. INFORMATION ARCHITECTURE

Primary Information (Always visible)

success: boolean
data: payload or null
error: { code, message, details? } or null

Secondary Information

message: optional human-readable string (present in some success responses).

Actions

Primary CTA: N/A (utility, not a UI feature).
Secondary Actions: N/A.

5. WIREFRAMES

[Excluded — backend infrastructure, no UI]

6. WIREFLOWS

Excluded.

7. PROTOTYPE

[Excluded — backend-only]

8. BACKEND SCHEMA

Database Tables

No dedicated tables. This is a pure TypeScript utility.

9. API ENDPOINTS

This feature is consumed by all API endpoints. Key integration points:

Endpoint	File	Usage
POST `/api/clerk/user-created`	`app/api/clerk/user-created/route.ts`	Uses `ApiResponseHelper.success()`, `.validationError()`, `.internalError()`
POST `/api/admin/suspend-user`	`app/api/admin/suspend-user/route.ts`	MIXED — auth uses raw `NextResponse.json()`, errors use `ApiResponseHelper.handleError()`, success uses raw `NextResponse.json({ success: true })`

10. DATA REQUIREMENTS

Frontend Needs

A single ApiErrorCode type union and ApiResponse<T> generic type for typing all fetch/axios calls.

API Calls Frontend Will Make

Every fetch to any API route — the consumer always expects { success, data, error }.

Caching Strategy

N/A — infrastructure layer.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

N/A.

API Response Time

Negligible overhead — static method calls returning NextResponse.json().

12. SECURITY & AUTHORIZATION

Who can access this feature?

Internal development utility. All route handlers call these methods.

Authorization Logic

Not applicable at the utility level — route handlers implement their own auth.

Data Validation

Zod validation is expected to be performed BEFORE calling ApiResponseHelper success methods. The utility does not validate payloads.

13. ERROR HANDLING

Error	Response
`ApiResponseHelper.validationError(msg, details)`	400 `{ success: false, error: { code: "VALIDATION_ERROR", message, details } }`
`ApiResponseHelper.unauthorized(msg)`	401 `{ success: false, error: { code: "UNAUTHORIZED", message } }`
`ApiResponseHelper.forbidden(msg)`	403 `{ success: false, error: { code: "FORBIDDEN", message } }`
`ApiResponseHelper.notFound(msg)`	404 `{ success: false, error: { code: "NOT_FOUND", message } }`
`ApiResponseHelper.conflict(msg)`	409 `{ success: false, error: { code: "CONFLICT", message } }`
`ApiResponseHelper.contentPolicyViolation(msg, details)`	422 `{ success: false, error: { code: "CONTENT_POLICY_VIOLATION", message, details } }`
`ApiResponseHelper.tokenLimitExceeded(msg, details)`	429 `{ success: false, error: { code: "TOKEN_LIMIT_EXCEEDED", message, details } }`
`ApiResponseHelper.internalError(msg, details?, rawError?)`	500 `{ success: false, error: { code: "INTERNAL_ERROR", message, details } }` — rawError logged server-side only
`ApiResponseHelper.handleError(error)`	500 `{ success: false, error: { code: "INTERNAL_ERROR", message } }` with full stack trace logged

14. TESTING CHECKLIST

Happy Path
□ ApiResponseHelper.success(data) returns correct JSON shape with 200 status.
□ ApiResponseHelper.created(data) returns correct shape with 201 status.
□ ApiResponseHelper.updated(data) returns correct shape with 200 status.
□ ApiResponseHelper.deleted() returns { success: true, data: null, error: null } with 200 status.

Edge Cases
□ ApiResponseHelper.validationError() returns 400 with VALIDATION_ERROR code.
□ ApiResponseHelper.handleError(Error instance) logs stack trace server-side, returns 500.
□ ApiResponseHelper.handleError(non-Error) handles gracefully.
□ ApiResponseHelper.tokenLimitExceeded() returns 429.

15. OPEN QUESTIONS

Should all legacy routes (e.g., suspend-user, app/api/get-role) be migrated to use exclusively ApiResponseHelper?
Should a lint rule enforce usage of ApiResponseHelper and forbid raw NextResponse.json()?

16. OUT OF SCOPE (v1.1+)

Auto-generated API documentation from schemas + response types.
Frontend SDK that wraps fetch with ApiResponse<T> typing out of the box.

17. SUCCESS METRICS

100% of API routes return consistent { success, data, error } shape (target: after full migration).
Zero instances of frontend code branching on different error response shapes.

18. DEPENDENCIES

This feature depends on:

Next.js NextResponse.json() (built-in).

These features depend on this:

All API routes, all Server Actions, all frontend fetch calls.

19. TIMELINE & OWNERSHIP

Implemented: W1.4 milestone.
Owner: scorevi

Document Version

1.0 - Initial version - 2026-06-29 08:26 UTC

1.1 - Added Document Version section and update author to have full name - 2026-06-29 08:49 UTC

1.1.1 - Minor edits - 2026-06-29 08:51 UTC