cadrumo.adapters.outbound.aeat.browser.errors module

Shared exception types for AEAT browser adapters.

The browser adapter wraps Playwright launch, context creation, evasion, navigation, site-health, and teardown failures in BrowserError with a stable BrowserFailureMode. That mode is copied into the structured context mapping so CLI and workflow error renderers can classify failures without parsing message text.

See also

adapters.outbound.aeat.browser.session.BrowserSession

Central owner that emits these browser errors.

adapters.outbound.aeat.browser.evasion.EvasionStrategy

Strategy hook whose setup failures surface as BrowserEvasionError.

adapters.outbound.aeat.browser.site_health_records.SiteHealthStatus

Site-health record carried separately by core.errors.hierarchy.SiteHealthError when AEAT itself returns a classified non-OK response.

class BrowserPreconditionCondition(*values)

Bases: StrEnum

Stable failed conditions observed at the AEAT browser boundary.

OPTIONAL_EXTRA_AVAILABLE

RUNTIME_STARTABLE

RUNTIME_STOPPABLE

SESSION_AVAILABLE

BROWSER_LAUNCHABLE

CONTEXT_CREATABLE

EVASION_SUPPORT_AVAILABLE

EVASION_APPLIED

PAGE_CONTENT_READABLE

BROWSER_CLOSEABLE

browser_no_action_verdict(*, condition, facts, outcome)

Delegate one fact-only browser refusal to the public verdict authority.

Parameters:

• condition (BrowserPreconditionCondition)

• facts (Mapping[str, str | int | bool])

• outcome (NoRecoveryOutcome)

exception BrowserError(message=None, *, failure_mode=None, context=None, translated_message=None, precondition_verdict=None)

Bases: TerminalPreconditionErrorMixin[PreconditionVerdict], CadrumoError

Base class for browser-related failures.

failure_mode may be a BrowserFailureMode member or an existing string value. When supplied, it is stored both on self.failure_mode and under context["failure_mode"] so downstream callers can branch on one stable tag.

Parameters:

• message (str | None)

• failure_mode (BrowserFailureMode | str | None)

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

• translated_message (str | None)

• precondition_verdict (PreconditionVerdict | None)

Return type:

None

code

exception BrowserValidationError(message=None, *, failure_mode=None, context=None, translated_message=None, precondition_verdict=None)

Bases: BrowserError

Raised when browser parameters or field values fail domain validation.

Pydantic callbacks translate this registered error to a plain ValueError at their narrow boundary while browser adapter code keeps the registered hierarchy.

Parameters:

• message (str | None)

• failure_mode (BrowserFailureMode | str | None)

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

• translated_message (str | None)

• precondition_verdict (PreconditionVerdict | None)

Return type:

None

code

exception BrowserEvasionError(message=None, *, failure_mode=None, context=None, translated_message=None, precondition_verdict=None)

Bases: BrowserError

Raised when browser evasion setup cannot be applied.

PlaywrightStealthEvasion raises this when playwright-stealth is unavailable. Failures that occur while BrowserSession applies any strategy are wrapped with BrowserFailureMode.EVASION_FAILED.

Parameters:

• message (str | None)

• failure_mode (BrowserFailureMode | str | None)

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

• translated_message (str | None)

• precondition_verdict (PreconditionVerdict | None)

Return type:

None

code

class BrowserFailureMode(*values)

Bases: StrEnum

Closed browser-backend failure modes emitted by the central session.

BrowserSession uses these values for one-live-context enforcement, browser launch, context creation, evasion, page-content reads, navigation transport failures, site-health classifications, and retained browser close failures.

SESSION_BUSY

OPTIONAL_EXTRA_UNAVAILABLE

PLAYWRIGHT_RUNTIME_START_FAILED

PLAYWRIGHT_RUNTIME_STOP_FAILED

BROWSER_NOT_PROVISIONED

BROWSER_LAUNCH_FAILED

CONTEXT_CREATE_FAILED

EVASION_FAILED

PAGE_CONTENT_FAILED

NAVIGATION_TIMEOUT

NAVIGATION_TRANSPORT_ERROR

SITE_HEALTH_NON_OK

BROWSER_CLOSE_FAILED