How to Return the Correct HTTP Status Code in a REST API

Why the wrong status code is a contract violation

HTTP status codes are not cosmetic - they are the protocol-level signal that clients, proxies, and retry libraries act on. When your API returns 200 OK for a validation failure, the client has to parse the response body to detect the error. Generic HTTP clients, retries, and error-handling middleware won't do that - they'll treat the request as successful.

The common mistake in Flask

In Flask, jsonify() returns a 200 OK by default. Forgetting the status argument in an error branch is easy to miss:

# Wrong - both branches return 200
@app.post("/orders")
def create_order():
    data = request.get_json()
    if not data or "item" not in data:
        return jsonify({"error": "missing required fields"})   # defaults to 200!
    order = save_order(data)
    return jsonify(order), 201

The validation path reaches the client as 200 OK with an error body. Any code that branches on response.status_code == 200 will treat the failure as a success.

The fix: pass the status code as the second return value

Flask accepts a (response, status_code) tuple from any route. Add the code:

@app.post("/orders")
def create_order():
    data = request.get_json(silent=True)
    if not data:
        return jsonify({"error": "Request body must be JSON"}), 400

    errors = []
    for field in ("customer", "item", "quantity"):
        if field not in data:
            errors.append(f"{field} is required")
    if errors:
        return jsonify({"error": "Validation failed", "details": errors}), 400

    order = save_order(data)
    return jsonify(order), 201

Now POST /orders with a missing field returns 400 Bad Request, and a successful creation returns 201 Created.

The codes that matter for REST APIs

Verify with curl

After the fix, test both paths explicitly:

# Should return HTTP/1.1 400 Bad Request
curl -i -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"item": "widget"}'

# Should return HTTP/1.1 201 Created
curl -i -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"customer": "alice", "item": "widget", "quantity": 2}'

Test suites that assert on both the status code AND the response shape catch this class of bug instantly - asserting on the body alone lets it slip through.