Skip to content

Errors and pages

ApplicationError 

ApplicationError(error: ApiError)

Bases: Exception

§4.2: a non-domain outcome of a contract call. error is the typed ApiError.

explanation property 

explanation: dict[str, Any]

MSG §3.3: the error's explanation as Python shows it (surface python).

ApiError dataclass 

ApiError(
    code: ApiErrorCode,
    message: str,
    retryable: bool,
    detail: Mapping[str, Any] = dict(),
)

§5.8: the one error shape. Domain outcomes are results, never an ApiError.

explanation property 

explanation: dict[str, Any]

MSG §3.3: the explanation document a transport attaches as detail.explanation — the one this error carries when it was projected, else rendered now (surface null). A property, never a field: it is not in as_document() and is stored nowhere (I2).

render_explanation 

render_explanation(
    surface: Literal["python", "cli"] | None = None,
) -> dict[str, Any]

The explanation rendered from the machine document (any carried one ignored).

SolveFailedError 

SolveFailedError(result: RunResult)

Bases: Exception

MSG §3.4: RunResult.raise_for_outcome on a run that did not end converged. Not an ApplicationError: a domain outcome is not an ApiError. result is the run result; the text is the failure's layered text (or, for a job that ended without a failure bundle, its status's).

Page dataclass 

Page(items: tuple[T, ...], next_cursor: str | None)

One page of a list (§4.1, §11.4): the items, and the cursor of the next page, or None when this is the last. A cursor is opaque to the caller.

as_document 

as_document(item: Callable[[T], Any]) -> dict[str, Any]

{items, next_cursor}, each item written by item (normally its as_document).

Projection dataclass 

Projection(
    subject_id: str,
    pointer: str,
    sha256: str,
    value: Any,
    truncated: bool,
    next_cursor: str | None,
)

§11.4: a bounded view of one document at an RFC 6901 pointer.

subject_id names the document (a revision or an artifact id). sha256 is that of the whole document as stored — a revision's canonical bytes, an artifact's file bytes, a bundle's directory hash — so two views of one document are told from views of two. value is the target, with objects deeper than the depth elided and long nested arrays cut; an array target is paged, and next_cursor fetches its next page. truncated: the size cap forced a smaller depth than the one asked for. The Python method returns the raw text; operations.project_response bounds it for every transport (§10.4).