How to Return 201 Created From a POST Endpoint (REST Status Codes)

Why a create should return 201, not 200

HTTP status codes are the contract between an API and everything that consumes it - browsers, caches, tests, and other services all branch on the number, not on the response body. REST assigns a specific code to each outcome:

• 200 OK - a generic success, used for reads and updates
• 201 Created - a new resource was created (often with a Location header)
• 204 No Content - success with an empty body, typical for a delete
• 400 Bad Request - the classic 4xx REST API error for invalid client input
• 404 Not Found - the resource does not exist
• 409 Conflict - the request conflicts with current state

Flask returns 200 by default. So a create endpoint that just returns a body silently sends the wrong code - the body looks right, but the contract is broken.

The bug: a bare return sends 200

The create handler builds the todo correctly but returns only the body, so Flask defaults to 200 OK:

@app.post("/api/todos")
def create_todo():
    title = (request.get_json(silent=True) or {}).get("title", "")
    todo_id = next(_next_id)
    TODOS[todo_id] = {"id": todo_id, "title": title}
    # BUG: returns a default 200 OK. A create should be 201 Created.
    return jsonify(TODOS[todo_id])

The React frontend only accepts 201 as success:

const res = await fetch('/api/todos', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'buy milk' }),
});
// Only treat 201 Created as success.
setStatus(res.status === 201 ? 'Added!' : `Unexpected status ${res.status}`);

The server saves the todo, the network call succeeds, but because the status is 200 and not 201, the check fails and the user sees "Unexpected status 200" instead of "Added!". The client is right to be strict - the API is the side that broke the convention.

The fix: return a (body, status) tuple

In Flask you set the status explicitly by returning a tuple whose second element is the code:

@app.post("/api/todos")
def create_todo():
    title = (request.get_json(silent=True) or {}).get("title", "")
    todo_id = next(_next_id)
    TODOS[todo_id] = {"id": todo_id, "title": title}
    return jsonify(TODOS[todo_id]), 201

That single , 201 is the whole fix. The body is unchanged - only the status code moves from 200 to 201, which is exactly what the client checks.

Verify with curl

Print just the status code so you can confirm the contract without reading the body:

pkill -f "python3 app.py"; python3 app.py > /tmp/flask.log 2>&1 &

curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8000/api/todos \
  -H 'Content-Type: application/json' -d '{"title":"buy milk"}'

This should print 201. Reload the React page, click "Add todo", and the status line now reads "Added!". The lesson generalizes: pick the code that matches the outcome - 201 for a create, 200 for a read, 400 for a bad request - because clients depend on it even when the body is fine.