Responses¶
Return whatever the handler has. Oxbrook decides how to send it.
| returned | sent as |
|---|---|
dict, list, int, float, bool |
JSON |
| a pydantic model | JSON, through pydantic's own serializer |
str |
text/plain; charset=utf-8 |
bytes |
application/octet-stream |
None |
204 No Content |
Response |
exactly what it says |
SSE |
a text/event-stream that stays open |
How values become JSON¶
One set of rules applies wherever Oxbrook writes JSON: a handler's return, a
Reply, an HTTPError's detail, an SSE event, a WebSocket message, a durable
topic, and an MCP tool result. They are pydantic's, so a value encodes the same
inside a model as outside one.
| value | JSON |
|---|---|
datetime |
ISO 8601 string, "2026-09-23T10:00:00.123000Z"; a naive one has no offset |
date, time |
ISO 8601 string, "2026-09-23", "10:00:00" |
timedelta |
ISO 8601 duration, "PT1M30S" |
UUID |
"12345678-1234-5678-1234-567812345678" |
Decimal |
string, "12.50", so no precision is lost to a float |
Enum |
its value |
set, frozenset, tuple, a generator |
array |
bytes inside a value |
UTF-8 string |
| a dict with non-string keys | the keys as strings |
| NaN, infinity | null, since JSON has no way to write them |
| a pydantic model, at any depth | what the model serializes to |
| a mapping-like object, such as a database row | object, from its keys() |
Anything else is refused with a 500 and a logged TypeError naming the type,
rather than sent as its repr: a repr in a response reaches the client looking
like data, and can carry what it should not. Convert it first, or give it a
pydantic model.
Values that are already plain JSON are encoded in Rust without building a Python string. Anything the table above had to convert takes pydantic's encoder, which is also native code.
Explicit responses¶
Return a Response when you need a specific status code, a content type that
is not JSON, or bytes that are already encoded and should not be touched.
from oxbrook import Response
@app.get("/teapot")
async def teapot(_: Request):
return Response(b"short and stout", status=418, content_type="text/plain")
Custom headers go alongside:
Response(b"...", headers={"x-request-id": "abc"})
Response(b"...", headers={"www-authenticate": ["Bearer", 'Basic realm="api"']})
A list sends the header once per item, which is how a response carries two challenges or two cookies.
body may be bytes or str; a str is encoded as UTF-8.
Status codes you get for free¶
Each of these is problem details,
application/problem+json, except 204, which has no body.
204when a handler returnsNone404when nothing matches the path405, with anAllowheader, when the path exists for another method413when the body is over the limit422when a parameter or body fails validation426on a plainGETto a WebSocket route500when the handler raises, with nodetail503, withRetry-After, when every worker is at its concurrency limit504when a handler does not respond withinrequest_timeout