Responses¶

Every HTTP request made through OxideHTTP returns a response object. It provides access to the response status, headers, and body.

Response Basics¶

async with OxideHTTP() as client:
    response = await client.get('https://api.example.com/users')

    print(response.status_code)
    print(response.headers)

The response exposes the following properties and methods:

Status Code¶

The status_code property returns an HTTPStatus value.

from oxidehttp.status import HTTPStatus

response = await client.get('/users')

if response.status_code == HTTPStatus.OK:
    print('Request succeeded')
elif response.status_code == HTTPStatus.NOT_FOUND:
    print('Resource not found')

HTTPStatus is an integer enum, so it can also be compared with integer status codes:

if response.status_code == 200:
    print('OK')

Headers¶

Access response headers through the headers property:

response = await client.get('/users')

content_type = response.headers.get('content-type')
request_id = response.headers.get('x-request-id')

print(content_type)
print(request_id)

The returned headers are provided by the underlying HTTP response.

Reading the Response Body¶

OxideHTTP provides three ways to access the response body.

Bytes¶

Use get_bytes() to retrieve the response body as a memoryview:

body = await response.get_bytes()

print(body)

This is useful when working with binary data or when you want to process the response without converting it to text.

Text¶

Use text() to decode the response body as UTF-8:

body = await response.text()

print(body)

Invalid UTF-8 sequences are replaced rather than raising a decoding error.

JSON¶

Use json() to decode a JSON response:

data = await response.json()

print(data)

OxideHTTP uses msgspec.json.decode for JSON decoding.

You can also decode the response directly into a msgspec.Struct:

import msgspec


class User(msgspec.Struct):
    id: int
    name: str


user = await response.json()

The json() method itself returns the decoded JSON value. It does not automatically convert the result into a custom Struct type.

To decode into a specific type, use msgspec directly with the response bytes:

user = msgspec.json.decode(await response.get_bytes(), type=User)

JSON Decoding Errors¶

Invalid JSON data raises OxideJSONDecodeError.

from oxidehttp.exceptions import OxideJSONDecodeError

try:
    data = await response.json()
except OxideJSONDecodeError:
    print('The response did not contain valid JSON')

See Exceptions for the exception hierarchy.

Cached Responses¶

OxideHTTP can return cached responses when caching is configured and a request meets the cache requirements.

Cached responses expose the same interface as regular responses:

response = await client.get('/users')

print(response.status_code)
print(await response.text())

Use is_cached to determine whether the response came from the cache:

if response.is_cached:
    print('Response was served from cache')
else:
    print('Response was fetched from the server')

Regular responses have is_cached set to False. Cached responses have it set to True.

See Caching for configuration and usage.

Response Types¶

OxideHTTP provides the following response classes:

These classes share the response access interface, allowing regular and cached responses to be handled consistently.

Error Handling¶

A response with an unsuccessful HTTP status does not necessarily mean the request raised an exception. Inspect status_code to handle HTTP errors:

response = await client.get('/users/123')

if response.status_code == 404:
    print('User not found')
elif response.status_code >= 400:
    print('HTTP request failed')

Transport errors, timeouts, and decoding errors are represented by OxideHTTP exceptions.

See Exceptions for details.

Related Documentation¶

• Requests
• Caching
• Exceptions
• Types