HTTP Status Codes Reference Guide

Every developer should understand HTTP status codes. This comprehensive guide covers all the codes you need to know.

Status Code Categories

| Range | Meaning | |-------|---------| | 1xx | Informational | | 2xx | Success | | 3xx | Redirection | | 4xx | Client Error | | 5xx | Server Error |

2xx - Success Codes

200 OK

The request succeeded. Most common response.

res.status(200).json({ message: 'Success' });

201 Created

A new resource was successfully created.

// POST /users
res.status(201).json({ user: newUser });

204 No Content

Request succeeded but no content to return.

// DELETE /users/123
res.status(204).send();

4xx - Client Errors

400 Bad Request

The server cannot process the request due to client error.

// Invalid JSON
res.status(400).json({ error: 'Invalid JSON' });

401 Unauthorized

Authentication is required or has failed.

// Missing token
res.status(401).json({ error: 'Authentication required' });

403 Forbidden

The server understands the request but refuses to authorize it.

// User doesn't have permission
res.status(403).json({ error: 'Access denied' });

404 Not Found

The requested resource doesn't exist.

// User not found
res.status(404).json({ error: 'User not found' });

422 Unprocessable Entity

The request was well-formed but couldn't be processed.

// Validation failed
res.status(422).json({ 
  errors: [{ field: 'email', message: 'Invalid format' }]
});

429 Too Many Requests

Rate limit exceeded.

res.status(429).json({ 
  error: 'Too many requests',
  retryAfter: 60
});

5xx - Server Errors

500 Internal Server Error

A generic server error occurred.

try {
  // some operation
} catch (error) {
  res.status(500).json({ error: 'Internal server error' });
}

502 Bad Gateway

The server received an invalid response from an upstream server.

503 Service Unavailable

The server is temporarily unavailable (overload, maintenance).

res.status(503).json({ 
  error: 'Service unavailable',
  retryAfter: 30
});

504 Gateway Timeout

The server didn't receive a timely response from upstream.

Common Status Code Mistakes

1. Using 200 for Errors

// Wrong
res.status(200).json({ error: 'Something went wrong' });

// Correct
res.status(400).json({ error: 'Something went wrong' });

2. 404 for Everything

// Wrong - missing resource returns 404
// Wrong - invalid input returns 404
// Wrong - unauthorized returns 404

// Correct
404 - resource doesn't exist
400 - invalid input
401 - not authenticated
403 - not authorized

3. Not Setting Proper Status Codes

// Wrong - default is 200
res.json({ error: 'Failed' });

// Correct
res.status(400).json({ error: 'Failed' });

API Design Best Practices

Use Consistent Status Codes

| Action | Status Code | |--------|-------------| | Create resource | 201 | | Update resource | 200 | | Delete resource | 204 or 200 | | Not found | 404 | | Validation error | 422 |

Include Error Details

res.status(400).json({
  error: 'Validation failed',
  details: [
    { field: 'email', message: 'Invalid format' },
    { field: 'password', message: 'Too short' }
  ]
});

Use Standard Error Types

const errorTypes = {
  VALIDATION_ERROR: 400,
  NOT_FOUND: 404,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  RATE_LIMITED: 429,
  INTERNAL_ERROR: 500
};

Quick Reference

| Code | Meaning | |------|---------| | 200 | Success | | 201 | Created | | 204 | No Content | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 422 | Unprocessable | | 429 | Too Many | | 500 | Server Error | | 502 | Bad Gateway | | 503 | Unavailable | | 504 | Timeout |

Conclusion

Use the right status codes for better API design. They help clients understand what happened and how to handle it. Reference this guide when designing your APIs.