design-standards

API Standards

HTTP Status Code Standards

4xx Client Errors

• 400 Bad Request - Invalid request format, missing required fields
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Authenticated but insufficient permissions
• 404 Not Found - Resource doesn't exist
• 409 Conflict - Resource state conflict (e.g., duplicate creation)
• 422 Unprocessable Entity - Valid format but semantic errors

5xx Server Errors

• 500 Internal Server Error - ONLY for unexpected server conditions
• 502 Bad Gateway - Upstream service failure
• 503 Service Unavailable - Service temporarily unavailable

FORBIDDEN Patterns

❌ NEVER return 500 for:

• Missing resources (use 404)
• Invalid user input (use 400)
• Authentication failures (use 401/403)
• Resource conflicts (use 409)

❌ NEVER return 404 for:

• Server errors (use 500)
• Authentication failures (use 401/403)

Response Format Standards

Success Responses

// ✅ Standard success format
return NextResponse.json({
  success: true,
  data: result,
  message: 'Operation completed successfully'
});

Error Responses

// ✅ Standard error format
return NextResponse.json({
  success: false,
  error: 'Human readable error message',
  details: 'Additional context for debugging',
  code: 'ERROR_CODE' // Optional error code
}, { status: appropriateStatus });

Validation Requirements

Input Validation

• ALWAYS validate required fields
• ALWAYS validate data types
• ALWAYS validate business rules
• ALWAYS return 400 for validation failures

Resource Existence

• ALWAYS check if resources exist before processing
• ALWAYS return 404 for missing resources
• NEVER let missing resources cause 500 errors

Authentication & Authorization

• ALWAYS check authentication first
• ALWAYS check permissions before processing
• ALWAYS return 401/403 for auth failures

API Request Flow