HTTP Status Codes Guide: Complete Reference for Developers

// Express.js examples
// 200 OK - Standard response with body
app.get('/users/:id', (req, res) => {
  const user = findUser(req.params.id);
  res.status(200).json(user);
});

// 201 Created - Resource created
app.post('/users', (req, res) => {
  const user = createUser(req.body);
  res.status(201)
    .location(`/users/${user.id}`)
    .json(user);
});

// 204 No Content - Success, no body needed
app.delete('/users/:id', (req, res) => {
  deleteUser(req.params.id);
  res.status(204).send();
});

// 301 - Permanent redirect (URL change, SEO migration)
app.get('/old-page', (req, res) => {
  res.redirect(301, '/new-page');
});

// 302 - Temporary redirect (A/B test, maintenance)
app.get('/promo', (req, res) => {
  res.redirect(302, '/current-sale');
});

// 303 - See Other (redirect after POST)
app.post('/orders', (req, res) => {
  const order = createOrder(req.body);
  // Redirect to GET the confirmation page
  res.redirect(303, `/orders/${order.id}/confirmation`);
});

// 304 - Not Modified (caching)
app.get('/api/data', (req, res) => {
  const etag = '"abc123"';
  if (req.headers['if-none-match'] === etag) {
    return res.status(304).send();
  }
  res.set('ETag', etag).json(data);
});

// 400 - Bad Request (validation error)
app.post('/users', (req, res) => {
  if (!req.body.email) {
    return res.status(400).json({
      error: 'Bad Request',
      message: 'Email is required',
      field: 'email'
    });
  }
});

// 401 - Unauthorized (no/invalid auth)
app.get('/profile', (req, res) => {
  if (!req.headers.authorization) {
    return res.status(401)
      .set('WWW-Authenticate', 'Bearer')
      .json({ error: 'Authentication required' });
  }
});

// 403 - Forbidden (authenticated but not allowed)
app.delete('/users/:id', (req, res) => {
  if (!req.user.isAdmin) {
    return res.status(403).json({
      error: 'Forbidden',
      message: 'Admin access required'
    });
  }
});

// 404 - Not Found
app.get('/users/:id', (req, res) => {
  const user = findUser(req.params.id);
  if (!user) {
    return res.status(404).json({
      error: 'Not Found',
      message: `User ${req.params.id} not found`
    });
  }
});

// 429 - Rate Limited
app.use((req, res, next) => {
  if (isRateLimited(req)) {
    return res.status(429)
      .set('Retry-After', '60')
      .json({ error: 'Too many requests. Try again in 60 seconds.' });
  }
  next();
});

// Global error handler
app.use((err, req, res, next) => {
  console.error('Unhandled error:', err);
  
  // Don't leak error details in production
  const message = process.env.NODE_ENV === 'production'
    ? 'Internal server error'
    : err.message;
  
  res.status(500).json({
    error: 'Internal Server Error',
    message,
    requestId: req.id // For debugging
  });
});

// 503 - Maintenance mode
app.use((req, res, next) => {
  if (isMaintenanceMode()) {
    return res.status(503)
      .set('Retry-After', '3600')
      .json({
        error: 'Service Unavailable',
        message: 'Server is under maintenance. Please try again later.'
      });
  }
  next();
});

// 101 - WebSocket upgrade
// Happens automatically with ws library
const WebSocket = require('ws');
const wss = new WebSocket.Server({ server });
// Client sends: Upgrade: websocket
// Server responds: 101 Switching Protocols

// 103 - Early Hints (Node.js 18+)
app.get('/page', (req, res) => {
  res.writeEarlyHints({
    link: '</style.css>; rel=preload; as=style'
  });
  // Continue processing...
  res.render('page');
});

// ❌ Bad: 200 with error in body
res.status(200).json({ success: false, error: 'Not found' });

// ✅ Good: Proper status code
res.status(404).json({ error: 'Not Found' });

// ❌ Bad: 404 for empty results
if (results.length === 0) {
  return res.status(404).json({ error: 'No results' });
}

// ✅ Good: 200 with empty array
res.status(200).json({ results: [], total: 0 });

// ❌ Bad: 500 for validation error
if (!isValid(data)) {
  return res.status(500).json({ error: 'Invalid data' });
}

// ✅ Good: 400 for client error
res.status(400).json({ error: 'Validation failed', details });