HTTP Status Codes: A Complete Reference

HTTP status codes are essential for web development and API design. They tell clients what happened with their request. Understanding them helps you debug issues and design better APIs.

What are HTTP Status Codes?

Every HTTP response includes a 3-digit status code indicating the result:

HTTP/1.1 200 OK
HTTP/1.1 404 Not Found
HTTP/1.1 500 Internal Server Error

Status Code Categories

Range	Category	Meaning
1xx	Informational	Request received, continuing process
2xx	Success	Request successfully received and processed
3xx	Redirection	Further action needed to complete request
4xx	Client Error	Request contains bad syntax or cannot be fulfilled
5xx	Server Error	Server failed to fulfill valid request

Using Our HTTP Status Code Reference

Our HTTP Status Codes tool provides:

1. Search by code or name
2. Click any code for detailed information
3. Quick reference by category
4. Complete descriptions for all codes

Common Status Codes

2xx Success

200 OK The request succeeded. Used for successful GET, PUT, PATCH, or DELETE.

201 Created A new resource was created. Used after successful POST requests.

204 No Content Success but no response body. Used after successful DELETE requests.

3xx Redirection

301 Moved Permanently Resource has a new permanent URL. Update bookmarks.

302 Found Resource temporarily at a different URL. Continue using original URL.

304 Not Modified Resource hasn’t changed since last request. Use cached version.

4xx Client Errors

400 Bad Request The request was malformed. Fix the request syntax.

401 Unauthorized Authentication required. Include valid credentials.

403 Forbidden Server understood but refuses to authorize. Access denied.

404 Not Found Resource doesn’t exist at this URL.

405 Method Not Allowed HTTP method not supported for this resource.

409 Conflict Request conflicts with current state of resource.

429 Too Many Requests Rate limit exceeded. Slow down requests.

5xx Server Errors

500 Internal Server Error Server encountered an unexpected condition.

502 Bad Gateway Server received an invalid response from upstream.

503 Service Unavailable Server is temporarily unable to handle requests.

504 Gateway Timeout Server didn’t receive timely response from upstream.

API Design Best Practices

Use Semantic Codes

// Good
app.post('/users', (req, res) => {
  const user = createUser(req.body);
  res.status(201).json(user);
});

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

// Avoid
app.post('/users', (req, res) => {
  res.status(200).json(user); // Should be 201
});

Common Patterns

Action	Method	Success Code	Error Codes
List	GET	200	401, 403
Create	POST	201	400, 401, 409
Read	GET	200	401, 404
Update	PUT/PATCH	200	400, 401, 404, 409
Delete	DELETE	204	401, 404

Code Examples

Express.js

app.get('/api/users/:id', async (req, res) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) {
      return res.status(404).json({ error: 'Not found' });
    }
    res.json(user);
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});

Python (Flask)

@app.route('/api/users/<int:id>', methods=['GET'])
def get_user(id):
    user = User.query.get(id)
    if not user:
        return jsonify({'error': 'Not found'}), 404
    return jsonify(user.to_dict())

Debugging with Status Codes

Common Issues

Always Getting 500

• Check server logs for exceptions
• Validate input data
• Check database connections

Unexpected 401/403

• Verify authentication token
• Check permissions
• Ensure correct headers

404 on Valid Routes

• Check URL spelling
• Verify route registration
• Check middleware order

Lesser-Known Codes

418 I’m a teapot April Fools’ joke that became a standard. Returned by servers that are teapot-shaped.

451 Unavailable For Legal Reasons Resource blocked for legal purposes (censorship, copyright).

426 Upgrade Required Client must upgrade protocol (usually to HTTPS/TLS).

Conclusion

Understanding HTTP status codes is fundamental for web development and API design. Use our HTTP Status Codes reference for quick lookups.

Remember: Using the right status code helps clients handle responses correctly and makes your API more intuitive!