aeat.core.errors package

Domain exception hierarchy and public error-registry surface.

Every subpackage should raise subclasses of AeatError to ensure predictable error handling throughout the application.

class SiteHealthEvidenceLike(*args, **kwargs)

Bases: Protocol

Structural view of the evidence block carried by a site-health status.

Declared in core.errors so SiteHealthError can type its payload without importing the adapter layer that produces it. The concrete record is adapters.outbound.aeat.browser._site_health.SiteHealthEvidence.

Members are read-only properties so the protocol matches covariantly: a concrete record may carry narrower member types (e.g. AnyHttpUrl for url) and still satisfy the structural view, which a mutable attribute declaration would reject.

property url: object

URL that was probed during the health check.

property http_status: object

HTTP status code returned by the probed URL.

property detected_markers: Sequence[object]

Sequence of markers detected in the response that triggered classification.

class SiteHealthStatusLike(*args, **kwargs)

Bases: Protocol

Structural view of a detected AEAT site-health classification.

Declared in core.errors so SiteHealthError can accept the status without a runtime or type-checking import of the adapter layer. The concrete record is adapters.outbound.aeat.browser._site_health.SiteHealthStatus.

Members are read-only properties so the protocol matches covariantly: the concrete SiteHealthStatus carries a concrete SiteHealthEvidence for evidence, which satisfies the SiteHealthEvidenceLike view only when the member is read-only.

property state: object

Classified site-health state (e.g. mantenimiento, WAF challenge, rate limit).

property evidence: SiteHealthEvidenceLike

Evidence block used to classify the detected state.

Returns a SiteHealthEvidenceLike carrying the URL, HTTP status, and detected markers that drove classification.

property observed_at: datetime

Timestamp at which the health check observation was recorded.

property retry_after_seconds: int | None

Suggested retry delay in seconds, or None when not provided.

exception AeatError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: Exception

Base exception for all AEAT domain errors.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception CoreError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Base error for internal framework and core-primitive failures.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception DecimalFormatError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: CoreError

Raised when core.decimal._format.format_decimal() receives an invalid argument.

Replaces the bare TypeError previously raised when value is None but none_value was not provided.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception RedactionError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: CoreError

Raised when a redaction helper receives an argument of the wrong type.

Replaces bare TypeError previously raised by core.redaction.redact() and core.redaction.redact_for_cli_output() when passed a non-str argument.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception CoreValidationError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: CoreError, ValueError

Raised when core primitives or configuration violate invariants.

Inherits from ValueError to maintain compatibility with Pydantic validators.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception ProfileAnswerTypeError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: CoreValidationError

Raised when a typed profile-answers field coercion receives an unexpected type.

Lives in core.errors so core.setup_answers.SetupAnswers can raise a typed error without importing application-layer wizard modules. Application-layer wizard code raises the narrower application.wizard._errors.WizardAnswerTypeError, which inherits from this class, so callers catching either type continue to work.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception AeatObservabilityError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Base class for observability-layer errors.

Lives in core.errors (rather than the leaf core.observability subpackage) so other subpackages can catch it without importing observability internals. Concrete subclasses are declared in core.observability._errors.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception FixtureProvisioningError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised when Google Workspace test-fixture provisioning fails.

Thrown by the provisioning and teardown scripts under scripts/ whenever a Drive / Sheets / Docs call cannot satisfy the catalogued intent (missing parent, quota exhausted, unexpected dedup result, etc).

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception ModeloFixtureError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised when a synthetic modelo-history fixture cannot be loaded.

Thrown by application.filing.testing when the fixtures directory cannot be resolved, a fixture file cannot be read, JSON decoding fails, or a payload fails strict pydantic validation (including the synthetic-only invariant checks on the synthetic and _comment fields).

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception SiteHealthError(*, status)

Bases: AeatError

Raised when AEAT site-health detection classifies a non-OK state.

Carries a SiteHealthStatusLike payload describing the detected state (mantenimiento, WAF challenge, rate limit, unreachable, unknown error) together with the evidence used to classify it. The workflow engine catches this error in a typed arm that precedes the generic exception handler so a planned mantenimiento never collapses into UNHANDLED_EXCEPTION.

The error lives in core.errors (and not in either leaf subpackage) to break the circular import between adapters.outbound.aeat.browser (which raises it) and application.workflow (which consumes it). The payload is typed through the SiteHealthStatusLike structural Protocol declared in this module, so no import of the adapter layer occurs at runtime or under type checking — the core-not-outer boundary is satisfied without an exclusion.

Parameters:

status (SiteHealthStatusLike)

Return type:

None

code: ClassVar[ErrorCode]

exception McpLaunchError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised when a repo-managed MCP process cannot be launched safely.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

exception ActiveProfilePointerError(*, path)

Bases: CoreError

Raised when the active-profile pointer is present but invalid.

A missing pointer is a clean cold-start state. A present pointer that cannot be parsed, decoded, read, or validated is storage metadata corruption and must not degrade to a root fallback database route.

Parameters:

path (object)

Return type:

None

code: ClassVar[ErrorCode]

exception NoActiveProfileError(message=None, *, context=None, suggestion=None, translated_message=None)

Bases: AeatError

Raised when an operation requires an active profile bucket and none is selected.

Bucket-scoped repositories (transaction catalogue, manual ledger, bucket-local aggregation) and the operator-initiated auth/sede flows refuse to operate without an active profile. The active-bucket precedence chain is a core concern (env var > pointer file), so the refusal that gates it lives in the core error taxonomy and is raised by core.require_active_bucket_id(). Callers that surface this to the operator map it to the standard cli.common.errors.no_active_profile message.

Parameters:

• message (str | None)

• context (dict[str, object] | None)

• suggestion (str | None)

• translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]

Subpackages

• aeat.core.errors.registry package
  • Submodules
    • aeat.core.errors.registry._adapters module
    • aeat.core.errors.registry._adapters_part1 module
    • aeat.core.errors.registry._adapters_part2 module
    • aeat.core.errors.registry._application module
    • aeat.core.errors.registry._application_part1 module
    • aeat.core.errors.registry._application_part2 module
    • aeat.core.errors.registry._core module
    • aeat.core.errors.registry._domain module
    • aeat.core.errors.registry._domain_part1 module
    • aeat.core.errors.registry._domain_part2 module
    • aeat.core.errors.registry._domain_part3 module
    • aeat.core.errors.registry._entrypoints module

Submodules

• aeat.core.errors._not_found module
  • CoreNotFoundError
    • CoreNotFoundError.code
• aeat.core.errors._registry module
  • ErrorCategory
    • ErrorCategory.ERROR
    • ErrorCategory.REFUSED
    • ErrorCategory.AUTH
    • ErrorCategory.INTEGRITY
    • ErrorCategory.FAIL
    • ErrorCategory.INTERNAL
    • ErrorCategory.LOCKED
  • ErrorCode
    • ErrorCode.code
    • ErrorCode.category
    • ErrorCode.message_key
    • ErrorCode.default_suggestion
    • ErrorCode.retryable
    • ErrorCode.runbook_id
  • ErrorEnvelope
    • ErrorEnvelope.code
    • ErrorEnvelope.category
    • ErrorEnvelope.message
    • ErrorEnvelope.suggestion
    • ErrorEnvelope.retryable
    • ErrorEnvelope.runbook_id
    • ErrorEnvelope.context
    • ErrorEnvelope.trace_id
  • register()
  • declared_error_codes()
  • bind_error_code()
  • get_registered_error_code()
  • resolve_output_language()
  • scrub_error_context()
  • build_error_envelope()
  • render_error_text()
  • render_error_json()
  • get_error_exit_code()
  • resolve_error_message()
  • get_error_suggestion()
• aeat.core.errors._severity module
  • BaseSeverity
    • BaseSeverity.INFO
    • BaseSeverity.WARNING
    • BaseSeverity.ERROR