aeat.adapters.outbound.aeat.auth._errors module

Shared exception taxonomy for outbound AEAT authentication.

Every class here inherits from AeatError, so the core error registry binds a stable ErrorCode and locale message key to the public auth failure surface. Certificate and Cl@ve Móvil providers raise these errors with translated_message keys when a provider precondition, verification probe, persisted-session check, or configuration guard refuses to continue.

See also

adapters.outbound.aeat.auth for the public auth surface, adapters.outbound.aeat.auth.AeatSession for successful live sessions, and adapters.outbound.aeat.auth.AeatLoginAssertion for verification outcomes that can be returned without raising.

exception AuthError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError

Base class for every outbound AEAT authentication domain error.

Catch this at adapter or CLI boundaries that need one AEAT-auth arm while preserving concrete subclasses such as AuthConfigurationError, AeatLoginAssertionError, and AeatSessionExpiredError for more specific handling.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthConfigurationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AuthError

Raised when required authentication settings are missing or malformed.

This covers provider selection and configuration refusals before browser or certificate work begins. Provider-specific subclasses such as adapters.outbound.aeat.auth.ClaveMovilConfigurationError keep their own public identity while remaining catchable through this shared configuration arm.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AuthValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AuthError, ValueError

Raised when authentication parameters or field values fail domain validation.

This error inherits from both AuthError and ValueError, ensuring compatibility with Pydantic’s validator contract while remaining catchable under the package’s unified error hierarchy. Certificate health and field-validation helpers use this class when invalid values should behave like validation failures and still carry auth-domain error metadata.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AeatLoginAssertionError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AuthError

Raised when an AEAT login assertion cannot be produced or trusted.

Providers raise this when a structural precondition blocks adapters.outbound.aeat.auth.AeatLoginAssertion creation, when a fresh login probe is invalid, or when persisted session metadata cannot be resumed safely. Call sites preserve translated_message so CLI and locale renderers can surface the specific refusal key without parsing the human-readable message.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception AeatSessionExpiredError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AuthError

Raised when an authenticated AEAT session is no longer usable.

Conditions feeding this error include an adapters.outbound.aeat.auth.AeatSession idle deadline that has elapsed, a failed single-shot reauthentication attempt, or an HTTP 401/403 surfaced by a downstream live-read call site. The registered error code is retryable so operator flows can prompt for a fresh authentication attempt.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]