Response Status Code

The same way you can specify a response model, you can also declare the HTTP status code used for the response with the parameter status_code in any of the path operations:

• @app.get()
• @app.post()
• @app.put()
• @app.delete()
• etc.

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

The status_code parameter receives a number with the HTTP status code.

It will:

• Return that status code in the response.
• Document it as such in the OpenAPI schema (and so, in the user interfaces):

In HTTP, you send a numeric status code of 3 digits as part of the response.

These status codes have an associated name to help recognize them, but the important part is the number.

In short:

• 100 - 199 are for "Information". You rarely use them directly. Responses with these status codes cannot have a body.
• 200 - 299 are for "Successful" responses. These are the ones you would use the most.
  • 200 is the default status code, which means everything was "OK".
  • Another example would be 201, "Created". It is commonly used after creating a new record in the database.
  • A special case is 204, "No Content". This response is used when there is no content to return to the client, and so the response must not have a body.
• 300 - 399 are for "Redirection". Responses with these status codes may or may not have a body, except for 304, "Not Modified", which must not have one.
• 400 - 499 are for "Client error" responses. These are the second type you would probably use the most.
  • An example is 404, for a "Not Found" response.
  • For generic errors from the client, you can just use 400.
• 500 - 599 are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes.

Let's see the previous example again:

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

201 is the status code for "Created".

But you don't have to memorize what each of these codes mean.

You can use the convenience variables from fastapi.status.

from fastapi import FastAPI, status

app = FastAPI()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

They are just a convenience, they hold the same number, but that way you can use the editor's autocomplete to find them:

Later, in the Advanced User Guide, you will see how to return a different status code than the default you are declaring here.