HTTP Responses and Status Codes

What it is

An HTTP response is the answer a server sends back after it processes a request.

It has three parts: a status line with a response code, a set of headers, and an optional body. Reading all three tells you whether the request worked and what happened.

The status code is a three digit number, and its first digit tells you the class of result.

How it works

You read a response from the top down, starting with the status code.

An example response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 55
Location: /v1/devices/77

{"id": 77, "name": "edge-sw1", "status": "provisioned"}

The first line gives the HTTP version, the status code and a short reason phrase. The headers follow, then a blank line, then the body.

Status code classes

Common success codes

Common redirection and client error codes

Server error codes

Response headers

Headers add detail about the answer.

• Content-Type tells you the format of the body, for example application/json.
• Content-Length gives the body size in bytes.
• Location often gives the address of a newly created resource.
• Retry-After can tell a client how long to wait after a rate limit or an outage.
• Set-Cookie sets a cookie, which some APIs use for sessions.

Each API decides which headers it returns, so check its documentation.

The response body

The body holds the data, usually as JSON. A good API also puts error details in the body of a 4xx or 5xx response. That message often names the field that failed.

Reading a response in Python

response = requests.get(BASE_URL + "/v1/devices/77", headers=headers)

print(response.status_code)
print(response.headers["Content-Type"])
print(response.json())

response.ok is True for any status below 400. The method response.raise_for_status() raises an exception for a 4xx or 5xx code.