Response

The Response object is returned by all HttpClient request methods. It provides a unified interface to access the status code, headers, body, and timing information of an HTTP response.

response = client.get("https://jsonplaceholder.typicode.com/todos/1")

print(response.status_code)   # 200
print(response.headers)       # {'Content-Type': 'application/json', ...}
print(response.body)          # b'{\n  "userId": 1, ...}'
print(response.elapsed)       # 0.123
print(response.elapsed_time)  # 123

Attributes

Attribute	Type	Description
`status_code`	`int`	HTTP status code of the response (e.g. `200`, `404`).
`headers`	`dict`	Dictionary of HTTP response headers.
`body`	`bytes`	Raw response body as bytes.
`elapsed`	`float`	Time taken to complete the request, in seconds. May be `None` if not measured.
`elapsed_time`	`int`	Time taken to complete the request, in milliseconds. Derived from `elapsed`. Returns `None` if `elapsed` is not available.

Note

elapsed and elapsed_time represent the same duration in different units. Use elapsed for precise float arithmetic and elapsed_time for display purposes.

Methods

text()

Returns the response body decoded as a UTF-8 string.

print(response.text())  # '{\n  "userId": 1, ...}'

Returns: str

json()

Parses and returns the response body as a JSON object.

data = response.json()
print(data["userId"])  # 1

Returns: Any — the parsed JSON value (dict, list, str, int, etc.)

Raises: ValueError if the response body is not valid JSON.

try:
    data = response.json()
except ValueError:
    print("Response is not valid JSON")

is_ok()

Returns True if the status code is in the 2xx range, False otherwise.

if response.is_ok():
    print("Request succeeded")
else:
    print("Request failed with status:", response.status_code)

Returns: bool

raise_for_status()

Raises an exception if the status code indicates a client error (4xx) or server error (5xx). Does nothing for 2xx and 3xx responses.

response = client.get("https://example.com/not-found")
response.raise_for_status()  # raises Exception: HTTP Error: 404

Raises: Exception with the message HTTP Error: <status_code>.

Warning

The behavior of raise_for_status() differs from the requests library. In requests, it raises an HTTPError with a detailed message including the URL and reason phrase. In lightreq, it raises a plain Exception with only the status code. Avoid using bare except Exception alongside this method, as it may silently catch unrelated errors.

Usage Patterns

Checking success before processing

response = client.get("https://api.example.com/data")

if response.is_ok():
    data = response.json()
else:
    print("Unexpected status:", response.status_code)

Guard with raise_for_status

try:
    response = client.get("https://api.example.com/data")
    response.raise_for_status()
    data = response.json()
except Exception as e:
    print("Request failed:", e)

Inspecting timing

response = client.get("https://api.example.com/data")

print(f"Completed in {response.elapsed_time} ms")  # e.g. "Completed in 123 ms"