angzarr_client.errors¶

Error types for the Angzarr client library.

Audit finding #59 (structural error model). Every error carries:

A static message — the same exact string for the same predicate failure across all call sites, suitable for log greppability, cross-language equality checks, and i18n keys.
A stable code identifier (SCREAMING_SNAKE) — programmatic dispatch and cucumber assertions key off this.
Structured details — runtime context (field name, type URL, domain, status code) that varies per call site.

Callers MUST NOT interpolate runtime values into message; that defeats the static-string contract. Put runtime values in details.

Mirrors Rust’s CommandRejectedError / ClientError with the same code values for cross-language symmetry.

Exceptions¶

`ClientError`	Base class for client errors.
`ConnectionError`	Failed to establish connection to the server.
`TransportError`	Transport-level error.
`GRPCError`	gRPC error from the server.
`InvalidArgumentError`	Invalid argument provided by caller.
`InvalidTimestampError`	Failed to parse timestamp.
`CommandRejectedError`	Command was rejected due to business rule violation.

Module Contents¶

exception angzarr_client.errors.ClientError(message: str, cause: Exception | None = None, *, code: str = '', details: collections.abc.Mapping[str, Any] | None = None)¶

Bases: Exception

Base class for client errors.

Predicate methods (is_not_found, is_precondition_failed, is_invalid_argument, is_connection_error) return False here and are overridden by subclasses. This lets callers write if err.is_not_found(): ... without casting.

Audit finding #59 fields:

message — static human-readable string
code — SCREAMING_SNAKE stable identifier
details — runtime context as dict[str, str]

Initialize self. See help(type(self)) for accurate signature.

message¶

code = ''¶

cause = None¶

details: dict[str, str]¶

is_not_found() → bool¶: Return True if this is a NOT_FOUND error.

is_precondition_failed() → bool¶: Return True if this is a FAILED_PRECONDITION error.

is_invalid_argument() → bool¶: Return True if this is an INVALID_ARGUMENT error.

is_connection_error() → bool¶: Return True if this is a connection or transport error.

exception angzarr_client.errors.ConnectionError(message: str = 'connection failed', *, code: str = 'CONNECTION_FAILED', details: collections.abc.Mapping[str, Any] | None = None)¶

Bases: ClientError

Failed to establish connection to the server.

Initialize self. See help(type(self)) for accurate signature.

is_connection_error() → bool¶: Return True if this is a connection or transport error.

exception angzarr_client.errors.TransportError(cause: Exception, *, code: str = codes.TRANSPORT_ERROR, details: collections.abc.Mapping[str, Any] | None = None)¶

Bases: ClientError

Transport-level error.

Initialize self. See help(type(self)) for accurate signature.

is_connection_error() → bool¶: Return True if this is a connection or transport error.

exception angzarr_client.errors.GRPCError(cause: grpc.RpcError, *, code: str = codes.GRPC_ERROR, details: collections.abc.Mapping[str, Any] | None = None)¶

Bases: ClientError

gRPC error from the server.

Initialize self. See help(type(self)) for accurate signature.

property grpc_code: grpc.StatusCode¶: Return the gRPC status code.

property grpc_details: str¶: Return the gRPC server-side details string.

status() → grpc.RpcError¶: Return the underlying gRPC RpcError (status).

is_not_found() → bool¶: Return True if this is a NOT_FOUND error.

is_precondition_failed() → bool¶: Return True if this is a FAILED_PRECONDITION error.

is_invalid_argument() → bool¶: Return True if this is an INVALID_ARGUMENT error.

is_connection_error() → bool¶: Return True for UNAVAILABLE status.

exception angzarr_client.errors.InvalidArgumentError(message: str, *, code: str = 'INVALID_ARGUMENT', details: collections.abc.Mapping[str, Any] | None = None)¶

Bases: ClientError

Invalid argument provided by caller.

Initialize self. See help(type(self)) for accurate signature.

is_invalid_argument() → bool¶: Return True if this is an INVALID_ARGUMENT error.

exception angzarr_client.errors.InvalidTimestampError(message: str = 'invalid timestamp', *, code: str = 'INVALID_TIMESTAMP', details: collections.abc.Mapping[str, Any] | None = None)¶

Bases: ClientError

Failed to parse timestamp.

Initialize self. See help(type(self)) for accurate signature.

exception angzarr_client.errors.CommandRejectedError(message: str, status_code: str = 'FAILED_PRECONDITION', *, code: str = '', details: collections.abc.Mapping[str, Any] | None = None, cover: Any | None = None)¶

Bases: ClientError

Command was rejected due to business rule violation.

Status codes and retry semantics:

FAILED_PRECONDITION: state-based rejection; retryable after refreshing state.
INVALID_ARGUMENT: bad input; not retryable.
NOT_FOUND: aggregate does not exist; not retryable — refetching won’t help.

Audit finding #59: callers pass a static message, a SCREAMING_SNAKE code, and structured details kwargs. The factory methods (precondition_failed / invalid_argument / not_found) bind the appropriate status_code.

The cover attribute is the addressing envelope (domain, root, correlation_id, edition) of the command that produced this rejection. Handlers do not populate it; the router stamps it from the incoming CommandRequest at the dispatch boundary so every rejection is traceable to its originating workflow without each call site having to thread the context.

Initialize self. See help(type(self)) for accurate signature.

status_code = 'FAILED_PRECONDITION'¶

cover = None¶

static precondition_failed(code: str, message: str, details: collections.abc.Mapping[str, Any] | None = None) → CommandRejectedError¶

Create a FAILED_PRECONDITION error for guard failures.

Parameters:

code – SCREAMING_SNAKE stable identifier (use a constant from angzarr_client.error_codes.codes).
message – Static human-readable message (no interpolation; use a constant from angzarr_client.error_codes.messages).
details – Structured runtime context — keys should be from angzarr_client.error_codes.keys.

static invalid_argument(code: str, message: str, details: collections.abc.Mapping[str, Any] | None = None) → CommandRejectedError¶: Create an INVALID_ARGUMENT error for input validation failures.

static not_found(code: str, message: str, details: collections.abc.Mapping[str, Any] | None = None) → CommandRejectedError¶: Create a NOT_FOUND error for missing-aggregate failures.

is_precondition_failed() → bool¶: Return True if this is a FAILED_PRECONDITION error.

is_invalid_argument() → bool¶: Return True if this is an INVALID_ARGUMENT error.

is_not_found() → bool¶: Return True if this is a NOT_FOUND error.