HTTP Status Codes — Complete Guide to API Response Statuses

In this tutorial, you will learn about HTTP Status Codes. We cover key concepts, practical examples, and best practices to help you master this topic.

HTTP status codes are three-digit response codes that indicate the result of an API request, classified into five ranges from informational to server errors.

What You'll Learn

• Each status code range and its meaning
• The most common codes for REST APIs
• Choosing the right code for each situation

Why It Matters

Correct status codes are the foundation of API error handling. They tell clients immediately whether a request succeeded, failed, or needs more work.

Status Code Ranges

Common Status Codes

Code Examples

from flask import jsonify

@app.route('/users/<int:user_id>')
def get_user(user_id):
    user = db.get_user(user_id)
    if not user:
        return jsonify({"error": "User not found"}), 404
    if not has_permission(user):
        return jsonify({"error": "Access denied"}), 403
    return jsonify(user.to_dict()), 200

@app.route('/users', methods=['POST'])
def create_user():
    data = request.get_json()
    if not data.get('email'):
        return jsonify({
            "error": "Validation failed",
            "details": {"email": "Email is required"}
        }), 400
    user = db.create_user(data)
    return jsonify(user.to_dict()), 201

Common Mistakes

1. Returning 500 for Client Errors

Client mistakes should get 4xx codes, not 500.

2. Using 200 for Created Resources

201 Created is more specific and tells clients the resource was created.

3. Returning 403 Instead of 401

Use 401 when auth is missing; 403 when auth is present but insufficient.

4. Not Using 429 for Rate Limiting

429 tells clients to back off and includes a Retry-After header.

5. Hiding 4xx Behind 200 Wrappers

Don't return 200 with {"status": "error"}. Use the appropriate 4xx code.

Practice Questions

1. What does a 201 status code indicate?
2. What is the difference between 401 and 403?
3. When should you use 204 No Content?
4. What status code indicates rate limiting?
5. Why is 500 incorrect for validation errors?

Answers:

1. The request succeeded and a new resource was created.
2. 401 means missing/invalid auth; 403 means authenticated but unauthorized.
3. For successful operations that don't return a body (e.g., DELETE).
4. 429 Too Many Requests.
5. Validation errors are the client's fault (4xx), not the server's (5xx).

Challenge: Create a decision tree for selecting the correct HTTP status code based on the request outcome. Cover at least 10 different scenarios.

FAQ

What's Next

Learn about Error Response Formats like RFC 7807 and JSON:API, then explore Validation Errors.