HTTP Status Codes

Status codes in the 2xx range indicate the request was successfully received, understood, and processed.

Common 2xx Codes

Code	Name	Usage
200	OK	Standard success response
201	Created	Resource created successfully
202	Accepted	Request accepted, processing pending
204	No Content	Success, no response body
206	Partial Content	Partial resource returned (range requests)

200 OK

The most common success code. Used for successful GET, PUT, PATCH, or DELETE.

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 1, "name": "Alice", "email": "alice@example.com"}

201 Created

Used when a new resource is created (typically after POST).

HTTP/1.1 201 Created
Location: /api/users/2
Content-Type: application/json

{"id": 2, "name": "Bob", "email": "bob@example.com"}

202 Accepted

Used for asynchronous operations. Request is accepted but not yet processed.

HTTP/1.1 202 Accepted
Content-Type: application/json

{"taskId": "abc-123", "status": "processing"}

204 No Content

Success with no response body. Common for DELETE operations.

HTTP/1.1 204 No Content

206 Partial Content

Used with Range requests for large files or media streaming.

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/4096
Content-Length: 1024
Content-Type: video/mp4

<binary data>

Status codes in the 3xx range indicate the client needs to take additional action.

Common 3xx Codes

Code	Name	Usage
301	Moved Permanently	Resource permanently moved (SEO preserved)
302	Found	Temporary redirect
303	See Other	Redirect with GET (after POST)
304	Not Modified	Cached version is valid
307	Temporary Redirect	Preserve method
308	Permanent Redirect	Permanent, preserve method

301 Moved Permanently

Resource permanently moved. Browser updates bookmarks. SEO link juice passed.

HTTP/1.1 301 Moved Permanently
Location: https://www.newsite.com/page
Cache-Control: max-age=3600

302 Found (Temporary Redirect)

Temporary redirect. Original URL still valid. Don't update bookmarks.

HTTP/1.1 302 Found
Location: /maintenance.html

304 Not Modified

Cached response is still valid. No body sent. Saves bandwidth.

HTTP/1.1 304 Not Modified
ETag: "abc123"
Cache-Control: max-age=3600

Redirect Best Practices

// After successful POST, redirect to GET
app.post('/users', (req, res) => {
  const user = createUser(req.body);
  res.redirect(303, `/users/${user.id}`);  // 303 changes to GET
});

// Permanent redirect for moved content
app.get('/old-page', (req, res) => {
  res.redirect(301, '/new-page');
});

// Temporary redirect during maintenance
app.get('/status', (req, res) => {
  res.redirect(307, '/maintenance');
});

Status codes in the 4xx range indicate the client made an error.

Common 4xx Codes

Code	Name	Usage
400	Bad Request	Malformed syntax or invalid data
401	Unauthorized	Authentication required
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource doesn't exist
405	Method Not Allowed	HTTP method not supported
409	Conflict	Resource state conflict
422	Unprocessable Entity	Validation errors
429	Too Many Requests	Rate limit exceeded

400 Bad Request

Client sent invalid data.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error": "Invalid email format", "field": "email"}

401 Unauthorized

Client must authenticate.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
Content-Type: application/json

{"error": "Authentication required"}

403 Forbidden

Client is authenticated but not authorized.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error": "Insufficient permissions"}

404 Not Found

Resource doesn't exist.

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error": "User not found"}

429 Too Many Requests

Rate limit exceeded.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

{"error": "Rate limit exceeded. Try again in 60 seconds."}

Status codes in the 5xx range indicate the server failed to fulfill a valid request.

Common 5xx Codes

Code	Name	Usage
500	Internal Server Error	Generic server error
501	Not Implemented	Feature not supported
502	Bad Gateway	Upstream server returned invalid response
503	Service Unavailable	Server overloaded or maintenance
504	Gateway Timeout	Upstream server too slow

500 Internal Server Error

Generic server error. Log the details for debugging.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{"error": "Internal server error", "requestId": "abc-123"}

502 Bad Gateway

Proxy/gateway received invalid response from upstream.

HTTP/1.1 502 Bad Gateway
Content-Type: text/html

<h1>Bad Gateway</h1>
<p>The proxy server received an invalid response from the upstream server.</p>

503 Service Unavailable

Server temporarily unavailable (overloaded, maintenance).

HTTP/1.1 503 Service Unavailable
Retry-After: 300
Content-Type: application/json

{"error": "Service temporarily unavailable. Please try again later."}

504 Gateway Timeout

Upstream server didn't respond in time.

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json

{"error": "Upstream server timeout"}

Error Handling Best Practices

// Always return meaningful error responses
app.use((err, req, res, next) => {
  console.error(err.stack);
  
  // Don't expose internal details in production
  res.status(err.status || 500).json({
    error: err.message || 'Internal server error',
    requestId: req.id
  });
});

// Log 5xx errors for monitoring
if (res.statusCode >= 500) {
  metrics.increment('server.error');
}