HTTP status codes

What are HTTP status codes?

Every time that a request is made towards an API, the server will not only reply with a response body... a HTTP status code is also given in the response. This status code will always be given back as a reply to the request and indicates whether the request could be answered properly.

The first digit of each three-digit status code begins with one of five numbers, 1 through 5; you may see this expressed as 1xx or 5xx to indicate status codes in that range. Each of those ranges indicates a different category of server response. The following ranges exist:

• 1xx - Informational - The request was received and the server will continue processing
• 2xx - Successful - The request was successfully completed
• 3xx - Redirection - The request was received, but there's a redirect of some kind
• 4xx - Client error - The request cannot be fulfilled (e.g. because of bad syntax)
• 5xx - Server error - Even though the request appears to be valid, the server could not process it correctly

Each status code also comes with a description.

HTTP status code 200: "OK"

Let's start with the most common status code: 200. This status code means that the request was successful and everything went 'according to plan' from the point of view of the server on which your API is running. The textual description of this status is "OK". Status code 200 is the default status that is sent back by FastAPI when nothing is out of the ordinary.

Inspecting requests

You can see which status code has been sent back by the server by opening Chrome, right-clicking on the webpage to open up the Inspect tool and then clicking on the tab Network. Next, sent a GET request by entering the link of a GET endpoint. Click on the request that appears.

Now click on 'View source' to see the raw response header.

Notice that the first line is saying HTTP/1.1 200 OK. This is the 'status line', which represents the protocol version, the response status code and a description of the status. In this particular case, it's telling us that everything was successful because status 200 with description "OK" was returned.

Tips

When your API is running, uvicorn will log some information about the requests that have been made. From these logs (that will appear in the terminal) you can see which endpoints were addressed with which method, as well as the status that was returned. For example:

HTTP status code 401: "Unauthorized"

Status code 401 "Unauthorized" indicates that you do not have the necessary rights to access the content of that endpoint. A possible cause might be that you have provided the wrong credentials.

For an example of how to program status 401: have a look at the chapter about HTTP Basic Auth.

HTTP status code 404: "Not Found"

The HTTP 404 "Not Found" response status code indicates that the server cannot find the requested resource (pay attention: it does not indicate whether the absence is temporary or permanent). Status code 404 is given back by FastAPI by default if it cannot find the requested endpoint, but can also be programmed in the API when a record in a database can not be found for example.

For an example of how to program status 404: have a look at the chapter about Implementing SQLAlchemy in FastAPI (go to the main.py file).

HTTP status code 500: "Internal Server Error"

The HTTP 500 "Internal Server Error" server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

This error response is a generic "catch-all" response. Usually, this indicates the server cannot find a better 5xx error code to response. Sometimes, server administrators log error responses like the 500 status code with more details about the request to prevent the error from happening again in the future.

When running an API with FastAPI, encountering status code 500 usually indicates that there is a problem in program code, for example an unexpected error thrown by Python.

Want to know more?

Do you want to get to know all existing HTTP status codes in a fun way? Have a look at the overview of all existing HTTP status codes on the website of HTTP Cats. And if you want to go straight to the interesting ones: status code 418 might be an excellent one to start with.