Tools and workflows

Python Requests Response: status, text, and JSON

Read status_code and headers, choose text or bytes, and handle JSON errors and empty HTTP responses before passing data to your application.

Use response.status_code to read the HTTP status and response.headers to inspect response metadata. Read the body with response.content for bytes, response.text for decoded text, or response.json() for JSON. A server can return valid JSON with a 400 status, so successful decoding tells you about the body format alone.

Check HTTP status before parsing the body

response.raise_for_status() raises an HTTP error for 4xx or 5xx statuses. It does not guarantee that the status is the exact success value your application expects. A job creation API may document 202 for accepted work while a detail endpoint may expect 200. Check the specific contract when the difference matters.

An error response may be valid JSON with a field like message. An unguarded call to .json() can decode that body successfully and hand the error to a parser expecting normal records. Test error handling separately from document parsing.

Pick text, bytes, or JSON intentionally

response.content exposes body bytes after Requests' applicable automatic content decoding. Use it for binary content or when you need to choose a text decoder yourself. It is not a packet capture or a copy of every network byte. response.text returns a decoded string according to the response encoding Requests selected. If the server labels its text incorrectly, inspect the documented format before choosing a different encoding.

response.json() decodes a JSON body into a Python object and can raise a decoding error for invalid JSON or an empty body. Decide what shapes are acceptable. A present but null field, a missing field, and an empty list can all mean different things to a report.

Trace a misleading reply

Imagine a catalog import points to a login page through a redirect. The final reply may have status 200 but carry HTML instead of records. Inspect its content type and final URL. When redirects matter, review the redirect history. That investigation is more useful than immediately editing your parsing code to accept unexpected input.

For a documented 204 response, handle success without calling .json(). If you expected JSON and get HTML, report the status, content type, and endpoint without copying the raw page into your logs.

Test response interpretation without reaching a site

You can use a synthetic response as a local example. This one has a JSON body and an error status.

from requests import Response, HTTPError

response = Response()
response.status_code = 400
response.url = "https://example.invalid/items"
response.headers["Content-Type"] = "application/json"
response._content = b'{"message": "label was missing"}'

print(response.json()["message"])
try:
    response.raise_for_status()
except HTTPError:
    print("The HTTP request failed.")

The first line shows that JSON decoding works. The second shows that HTTP status still signals a failure. Assigning _content is only a fixture shortcut using a private attribute. For a maintained test suite, use a supported HTTP client mock, a controlled fixture server, or test your code's parsing function directly with bytes. The example makes no network request.

Check business success after HTTP success

A bulk report API might return a successful HTTP response with a page summary and a warning that some records were unavailable. If the documented contract identifies such warnings, preserve them. Marking every 200 response as complete makes the report difficult to trust when source coverage matters. Use a deliberate completion field such as “complete,” “partial,” or “unavailable” based on what you know.

Decide what to record safely

A small diagnostic can include the status, content type, and a request identifier from the service if provided. Treat the body and headers as potentially sensitive. Cookies, tokens, emails, and signed URLs can appear in places you did not anticipate. Capture only the fields that help explain an incident.

Test the reader with a known good reply, an error reply containing JSON, and a success reply with the wrong data shape. Those cases exercise three separate decisions. They let you refine parsing and error handling without repeatedly calling the real service.

Sources and further reading

Related reading

Browse Tools and workflows · Explore project tutorials

Search PythonProjects.org