---
sidebar:
  label: roboto.http.response
  order: 7
title: roboto.http.response
---
## Module Contents

### BatchResponse

```python
class roboto.http.response.BatchResponse(/, **data: Any)
```

`from roboto.http import BatchResponse`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L116-L179)

Bases: `pydantic.BaseModel`, `Generic[Model]`

The response to a batch request, holding one element per request element, in the order the request sent them.

Every element of a batch is applied or refused on its own, so a batch can come back partly applied. [`succeeded`](/reference/python-sdk/roboto/http/response#roboto.http.response.BatchResponse.succeeded) and [`failed`](/reference/python-sdk/roboto/http/response#roboto.http.response.BatchResponse.failed) split the outcomes for a caller that does not care which request element produced which; read `responses` to trace an outcome back to the request element at its position.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BatchResponse.responses** (`list[BatchResponseElement[Model]]`)

**Properties**

- **BatchResponse.failed** (`list[roboto.exceptions.RobotoDomainException]`): The exception the platform reported for each element it refused, in request order.
- **BatchResponse.succeeded** (`list[Model]`): The result the platform returned for each element it applied, in request order.

#### BatchResponse.map_data()

```python
def map_data(
    transform: collections.abc.Callable[[Model], MappedModel],
) -> BatchResponse[MappedModel]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L137-L158)

Convert what each applied element carries, leaving positions and failures untouched.

A batch call parses the platform's answer into records and uses this to hand the caller domain objects instead: a `SessionRecord` becomes a `Session`. `transform` runs only on elements carrying data; a refused element keeps its exception, and every element keeps its position.

**Parameters**

- **transform** (`collections.abc.Callable[[Model], MappedModel]`): Builds the domain object an applied element's record stands for.

**Returns**

- `BatchResponse[MappedModel]`: A batch holding one element per element of this one, in the same order.

#### BatchResponse.single()

```python
def single() -> Model
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L160-L179)

The result carried by the only element of a one-element batch.

A singular call such as [`create_session()`](/reference/python-sdk/roboto/domain/devices/device#roboto.domain.devices.device.Device.create_session) sends its one element through the plural counterpart and unwraps the answer with this, so its caller gets a raised exception rather than a batch to inspect.

**Raises**

- [`RobotoDomainException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoDomainException): Whatever the platform refused the element with.
- [`RobotoInternalException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoInternalException): The batch does not hold exactly one element, or holds one carrying neither a result nor an error.

**Returns**

- `Model`

### BatchResponseElement

```python
class roboto.http.response.BatchResponseElement(/, **data: Any)
```

`from roboto.http import BatchResponseElement`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L36-L113)

Bases: `pydantic.BaseModel`, `Generic[Model]`

One element of a response to a batch request, holding `data` when the operation succeeded and `error` when it failed, never both. An element holding neither reports an operation that returns no content, the batch equivalent of a 204 answer to a singular call.

**Parameters**

- **data** (`Any`)

**Attributes**

- **BatchResponseElement.data** (`Model | None`) = `None`
- **BatchResponseElement.error** (`roboto.exceptions.RobotoDomainException | None`) = `None`
- **BatchResponseElement.model_config**: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### BatchResponseElement.serialize_error()

```python
def serialize_error(
    value: Optional[roboto.exceptions.RobotoDomainException],
    info: pydantic.SerializationInfo,
) -> Optional[dict[str, Any]]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L108-L113)

**Parameters**

- **value** (`Optional[roboto.exceptions.RobotoDomainException]`)
- **info** (`pydantic.SerializationInfo`)

**Returns**

- `Optional[dict[str, Any]]`

#### BatchResponseElement.validate_error()

```python
def validate_error(value: Any) -> Optional[roboto.exceptions.RobotoDomainException]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L52-L105)

Build the exception an element was refused with, in whichever form the failure arrived.

Three forms reach this: an exception object, which is what an element copied from another batch carries; the envelope [`RobotoDomainException.to_dict()`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoDomainException.to_dict) produces; and that envelope as JSON text, which is what [`RobotoDomainException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoDomainException) declares to pydantic. Only a literal `None` yields `None`, which is how an element the platform applied or answered with no content arrives.

Any other value is a refusal, whatever shape it has. An envelope naming an exception class this release does not define, one missing its code or message, JSON that is not an envelope, and text that is not JSON all read as a [`RobotoUnrecognizedErrorException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnrecognizedErrorException) carrying whatever code and message could be recovered, with the value's own text as the message when no message could be. That way a refused element is always in [`BatchResponse.failed`](/reference/python-sdk/roboto/http/response#roboto.http.response.BatchResponse.failed), so a caller checking `failed` before treating a batch as done cannot mistake a garbled refusal for success.

`plain` mode replaces the validation the `error` annotation would otherwise apply. That annotation reads JSON text, so it would reject the exception object returned here.

**Parameters**

- **value** (`Any`)

**Returns**

- `Optional[roboto.exceptions.RobotoDomainException]`

### DEFAULT_RESPONSE_JSONPATH

```python
roboto.http.response.DEFAULT_RESPONSE_JSONPATH = ('data',)
```

`from roboto.http.response import DEFAULT_RESPONSE_JSONPATH`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L33-L33)

### HttpResponse

```python
class roboto.http.response.HttpResponse(response: urllib.response.addinfourl)
```

`from roboto.http.response import HttpResponse`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L324-L383)

**Parameters**

- **response** (`urllib.response.addinfourl`)

**Properties**

- **HttpResponse.headers** (`dict[str, str] | None`): Return type: `Optional[dict[str, str]]`
- **HttpResponse.readable_response** (`urllib.response.addinfourl`)
- **HttpResponse.status** (`http.HTTPStatus`)

#### HttpResponse.to_dict()

```python
def to_dict(json_path: Optional[collections.abc.Sequence[str]] = None) -> Any
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L370-L376)

**Parameters**

- **json_path** (`Optional[collections.abc.Sequence[str]]`)

**Returns**

- `Any`

#### HttpResponse.to_int()

```python
def to_int() -> int
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L382-L383)

**Returns**

- `int`

#### HttpResponse.to_paginated_list()

```python
def to_paginated_list(record_type: Type[PydanticModel]) -> PaginatedList[PydanticModel]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L346-L351)

**Parameters**

- **record_type** (`Type[PydanticModel]`)

**Returns**

- `PaginatedList[PydanticModel]`

#### HttpResponse.to_record()

```python
def to_record(
    record_type: Type[PydanticModel],
    json_path: Optional[collections.abc.Sequence[str]] = DEFAULT_RESPONSE_JSONPATH,
) -> PydanticModel
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L353-L358)

**Parameters**

- **record_type** (`Type[PydanticModel]`)
- **json_path** (`Optional[collections.abc.Sequence[str]]`)

**Returns**

- `PydanticModel`

#### HttpResponse.to_record_list()

```python
def to_record_list(
    record_type: Type[PydanticModel],
    json_path: Optional[collections.abc.Sequence[str]] = DEFAULT_RESPONSE_JSONPATH,
) -> list[PydanticModel]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L360-L365)

**Parameters**

- **record_type** (`Type[PydanticModel]`)
- **json_path** (`Optional[collections.abc.Sequence[str]]`)

**Returns**

- `list[PydanticModel]`

#### HttpResponse.to_string()

```python
def to_string()
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L378-L380)

#### HttpResponse.to_string_list()

```python
def to_string_list() -> list[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L367-L368)

**Returns**

- `list[str]`

### InvalidPaginationTokenError

```python
exception roboto.http.response.InvalidPaginationTokenError
```

`from roboto.http import InvalidPaginationTokenError`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L231-L241)

Bases: `ValueError`

Raised when a pagination token cannot be parsed.

A pagination token is opaque to clients, so one that fails to decode or carries an unsupported scheme reflects bad caller input — a fabricated, truncated, or stale token — rather than a server fault. Subclasses `ValueError` so existing callers that catch `ValueError` around [`PaginationToken.from_token()`](/reference/python-sdk/roboto/http/response#roboto.http.response.PaginationToken.from_token) keep working unchanged, while callers that want to distinguish this recoverable input error (e.g. to surface an actionable message instead of a generic 500 or runtime exception) can catch it specifically.

### MappedModel

```python
roboto.http.response.MappedModel
```

`from roboto.http.response import MappedModel`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L30-L30)

### Model

```python
roboto.http.response.Model
```

`from roboto.http.response import Model`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L29-L29)

### PaginatedList

```python
class roboto.http.response.PaginatedList(/, **data: Any)
```

`from roboto.http import PaginatedList`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L182-L199)

Bases: `pydantic.BaseModel`, `Generic[Model]`

A list of records pulled from a paginated result set. It may be a subset of that result set, in which case `next_token` will be set and can be used to fetch the next page.

**Parameters**

- **data** (`Any`)

**Attributes**

- **PaginatedList.items** (`list[Model]`): Roboto entities in this page of results.

- **PaginatedList.next_token** (`str | None`) = `None`: Opaque token to fetch the next page of results.

  If `None`, then this is the last page of results.

- **PaginatedList.total_count** (`int | None`) = `None`: Total result set size, if available.

### PaginationToken

```python
class roboto.http.response.PaginationToken(
    scheme: PaginationTokenScheme,
    encoding: PaginationTokenEncoding,
    data: Any,
)
```

`from roboto.http import PaginationToken`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L244-L321)

A pagination token that can be treated as a truly opaque token by clients, with support for evolving the token format over time.

**Parameters**

- **scheme** (`PaginationTokenScheme`)
- **encoding** (`PaginationTokenEncoding`)
- **data** (`Any`)

**Properties**

- **PaginationToken.data** (`Any`)

#### PaginationToken.decode()

```python
@staticmethod
def decode(data: str) -> str
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L264-L268)

Base64 decode the data, adding back any trailing padding ("=") as necessary to make data properly Base64.

**Parameters**

- **data** (`str`)

**Returns**

- `str`

#### PaginationToken.empty()

```python
@staticmethod
def empty() -> PaginationToken
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L255-L256)

**Returns**

- `PaginationToken`

#### PaginationToken.encode()

```python
@staticmethod
def encode(data: str) -> str
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L259-L261)

Base64 encode the data and strip all trailing padding ("=").

**Parameters**

- **data** (`str`)

**Returns**

- `str`

#### PaginationToken.from_token()

```python
@classmethod
def from_token(token: Optional[str]) -> PaginationToken
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L271-L289)

**Parameters**

- **token** (`Optional[str]`)

**Returns**

- `PaginationToken`

#### PaginationToken.json_token()

```python
@classmethod
def json_token(data: Any) -> PaginationToken
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L292-L297)

**Parameters**

- **data** (`Any`)

**Returns**

- `PaginationToken`

#### PaginationToken.to_token()

```python
def to_token() -> str
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L319-L321)

**Returns**

- `str`

### PaginationTokenEncoding

```python
class roboto.http.response.PaginationTokenEncoding(*args, **kwds)
```

`from roboto.http import PaginationTokenEncoding`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L218-L222)

Bases: `enum.Enum`

Pagination token encoding enum

**Attributes**

- **PaginationTokenEncoding.Json** = `'json'`
- **PaginationTokenEncoding.Raw** = `'raw'`

### PaginationTokenScheme

```python
class roboto.http.response.PaginationTokenScheme(*args, **kwds)
```

`from roboto.http import PaginationTokenScheme`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L225-L228)

Bases: `enum.Enum`

Pagination token scheme enum

**Attributes**

- **PaginationTokenScheme.V1** = `'v1'`

### PydanticModel

```python
roboto.http.response.PydanticModel
```

`from roboto.http.response import PydanticModel`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L31-L31)

### StreamedList

```python
class roboto.http.response.StreamedList(/, **data: Any)
```

`from roboto.http import StreamedList`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L202-L215)

Bases: `pydantic.BaseModel`, `Generic[Model]`

A StreamedList differs from a PaginatedList in that it represents a stream of data that is in process of being written to. Unlike a result set, which is finite and complete, a stream may be infinite, and it is unknown when or if it will complete.

**Parameters**

- **data** (`Any`)

**Attributes**

- **StreamedList.has_next** (`bool`)
- **StreamedList.items** (`list[Model]`)
- **StreamedList.last_read** (`str | None`)

### logger

```python
roboto.http.response.logger
```

`from roboto.http.response import logger`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/http/response.py#L27-L27)