cadrumo.application.live.errors module

Application-level live AEAT read workflow errors.

Every refusal raised here carries a registered locale key plus machine facts; no raise site authors an operator-facing sentence, so str(exc) renders the key and the prose is resolved once, per locale, at the presentation boundary.

A subset of these refusals is additionally a safety disposition: the live read observed a fact that makes retrying the same call actively unsafe rather than merely futile – a captured justificante that does not belong to the filing it would be stamped onto, a notification document that belongs to a different certificado, an AEAT observation AEAT no longer reports as active. Those raise sites attach a PreconditionVerdict whose no_recovery_outcome is SAFETY, so the CLI boundary projects an explicit “there is deliberately no recovery here” rather than reaching for a retry the operator should not run.

class LiveIvaAcquisitionFailureMode(*values)[source]

Bases: StrEnum

Application-level IVA live acquisition failure modes.

AUTHENTICATED
NO_CLAVE_PROMPT
OPERATOR_TIMEOUT
QR_REQUIRED
CERTIFICATE_REQUIRED
WRONG_IDENTITY
AEAT_403
DOM_DRIFT
PENDING_CLAVE_REQUEST
LIVE_NAVIGATION_FAILED
UNKNOWN
class LiveIvaAcquisitionFailureProtocol(*args, **kwargs)[source]

Bases: Protocol

Application-facing live-IVA failure classification exposed by adapters.

Outbound adapters own their provider-specific exception classes and local tax-portal failure taxonomies. When one of those exceptions crosses into live application orchestration, it exposes this one application-owned classification rather than asking the application to identify the concrete adapter type or enum that produced it.

property live_iva_failure_mode: LiveIvaAcquisitionFailureMode

Return the application-level mode for this adapter failure.

class LiveReadPrecondition(*values)[source]

Bases: StrEnum

Closed failed-condition identities for live-read safety dispositions.

Membership is deliberately narrow. A condition earns a place here only when an automatic retry of the same live read would be unsafe – it would attach evidence to the wrong filing, take custody of a document under the wrong certificado, or persist an observation AEAT no longer stands behind. An input refusal an operator fixes by supplying a different argument is not a safety disposition and stays a plain typed refusal.

JUSTIFICANTE_MATCHES_CAPTURE
JUSTIFICANTE_MATCHES_FILING_RECORD
JUSTIFICANTE_FILING_EVIDENCE_ABSENT
JUSTIFICANTE_FILING_IDENTITY_RESOLVED
NOTIFICATION_DOCUMENT_MATCHES_ROW
FILED_OBSERVATION_ACTIVE
SURFACE_COMPLETED
live_read_no_recovery_verdict(condition, *, facts, outcome=NoRecoveryOutcome.SAFETY)[source]

Return one explicitly non-actionable outcome for a live-read refusal.

The facts name exactly what the live read observed; the closed outcome is what stops a downstream boundary from manufacturing a recovery command out of that observation. No action is bound because none of these conditions has a safe automatic remedy – resolving them is an operator judgement made against AEAT’s own record.

Parameters:
Return type:

PreconditionVerdict

Returns:

The PreconditionVerdict carrying the failed condition and its explicit no-recovery outcome.

exception LiveApplicationError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: TerminalPreconditionErrorMixin[PreconditionVerdict], CadrumoError

Raised when live AEAT read orchestration fails.

Accepts an optional precondition_verdict so a raise site that has already decided a failure has no safe recovery can say so in typed form. The verdict is surfaced through terminal_precondition_verdict, the attribute the shared CLI exception boundary reads.

Parameters:
Return type:

None

code
exception LiveApplicationInputError(message=None, *, context=None, translated_message=None, precondition_verdict=None)[source]

Bases: LiveApplicationError

Raised when a live AEAT read request is not executable.

Parameters:
Return type:

None

code
exception LiveIvaSurfaceTimeoutError(message, *, surface, timeout_ms, progress_context=None)[source]

Bases: LiveApplicationError

Raised when one live IVA read surface exceeds its orchestration timeout.

Parameters:

  • message (str)

  • surface (str)

  • timeout_ms (int)

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

Return type:

None

code
classify_live_iva_acquisition_failure(exc)[source]

Resolve an application-level mode from an application or adapter failure.

Outbound adapters translate their concrete failures into LiveIvaAcquisitionFailureProtocol before they cross this boundary. The application therefore never identifies an adapter exception or reads an adapter-owned taxonomy here.

Return type:

LiveIvaAcquisitionFailureMode

Returns:

A LiveIvaAcquisitionFailureMode member identifying the failure category.

Parameters:

exc (BaseException)