aeat.application.modelo._action_errors module

Typed exception vocabulary for modelo application actions.

The classes in this module are the stable application-layer errors raised by modelo work-unit lifecycle, calculation, verification, filing, amendment, external-import, and workflow-gate services. They all inherit from aeat.domain.modelos._errors.ModeloError so CLI and API error boundaries can route them through the central error-code registry without depending on the implementation module that raised them.

Most classes are deliberately thin taxonomy markers whose operator-facing code, message key, and suggestion live in aeat.core.errors.registry. The richer contracts are kept here when the exception must preserve domain context without leaking it into rendered error payloads, as with ModeloWorkflowGateError and its private WorkflowResult.

See also

aeat.application.modelo:

Public package facade for these action errors.

aeat.core.errors.registry:

Maps these exception classes to stable error codes and suggestions.

aeat.application.modelo._workflow_gate:

Raises ModeloWorkflowGateError after persisting an aborted workflow run.

aeat.application.modelo._profile_readiness_gate:

Raises ModeloProfileReadinessError for filing-grade profile preflight failures.

Legal anchors attached to workflow-gate refusal observations.

The cross-period clean-state finding tests assert these ids remain present in the workflow-gate provenance payload. They correspond to the Ley 58/2003 articles that frame declaration, self-assessment, and complementary declaration flows.

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

Bases: ModeloError, KeyError

Raised when a work-unit lookup or mutation targets a missing id.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when discard is invoked on a work unit already discarded.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when a mutation targets a discarded work unit.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError, CoreNotFoundError

Raised when a calculation revision lookup fails.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when a state transition is requested from an incompatible source state.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError, KeyError

Raised when a filing record lookup fails.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError, KeyError

Raised when a verification report lookup fails.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when the modelo-amend path lacks imported official evidence.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when the modelo-amend path targets a non-current filing record.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when the requested amendment kind is not legally available for the period.

AEAT’s amendment mechanism changed over time: the unified autoliquidación rectificativa (LGT art. 120.4, RD 117/2024) replaced the dual complementaria/solicitud-de-rectificación regime (LGT art. 122.2 / art. 120.3) only from the period each modelo’s own orden establishes (see aeat.core._amendment_kind_regime). Requesting rectificativa for a pre-adoption period, or complementaria for a modelo/period where rectificativa has replaced it as the ordinary correction mechanism, is refused rather than silently accepted or silently downgraded — the accepted kind set for the resolved period is always named in the refusal.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when a pre-rectificativa complementaria would decrease liability.

Before the autoliquidación rectificativa unification (LGT art. 120.4), a self-filed complementaria (LGT art. 122.2) can only ever RAISE the taxpayer’s own declared tax due (or lower a requested devolución): “los obligados tributarios podrán presentar autoliquidaciones complementarias” when the new autoliquidación yields “un importe a ingresar superior… o una cantidad a devolver inferior”. A correction that LOWERS the declared liability is not a complementaria in law; it requires the separate solicitud de rectificación procedure (LGT art. 120.3, developed by RGAT art. 126-128). Filing a liability-decreasing correction as a complementaria would silently misrepresent which legal procedure the taxpayer used, so it is refused with guidance toward the correct procedure rather than silently accepted.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when a persisted calculation revision has drifted from its content-addressed id.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when the external-filing import path cannot persist an imported baseline.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when an operator-supplied local observation cannot be persisted.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when a filing-grade workflow lacks clean prior-filing proof.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception ModeloWorkflowGateError(result)[source]

Bases: ModeloError

Raised when the workflow gate refuses an internal file transition.

The constructor stores the live WorkflowResult on a private attribute and exposes it through result. The rendered error context contains only primitive machine codes (abort_code and stage), which keeps CLI JSON/text payloads stable while allowing telemetry and tests to inspect the full workflow run.

See also

aeat.application.modelo._workflow_gate.run_revision_workflow_gate():

Persists the workflow run and raises this error for aborted results.

aeat.core.errors.render_error_text():

Renders the primitive context without serialising the live result.

Parameters:

result (WorkflowResult)

Return type:

None

property result: WorkflowResult

Return the live WorkflowResult that triggered the abort.

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

Bases: ModeloError

Raised when an amendment override targets an undeclared casilla id.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when the corrected casilla map fails verification.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when the registry snapshot for a work unit cannot be resolved.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when bucket-derived aggregation bindings conflict with caller input.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when Modelo 202 lifecycle work lacks required calculation bindings.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when filing-grade modelo work starts with missing active-profile facts.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when an engine-result casilla has no registry definition.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when an unknown applicability filter name is encountered.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when an operator elects a Modelo 303 refund for an ineligible period.

A non-REDEME taxpayer may request a negative Modelo 303 result back as a refund (devolución, Tipo de declaración D) only in the last filing period of the year (the annual liquidación, Ley 37/1992 art. 116). Electing devolver for any earlier period is refused rather than silently downgraded to compensación — a silent downgrade would hide that the operator’s refund request was discarded, and a silent upgrade would file a refund the law does not permit for the period. The fix is operator-driven: carry the credit forward (compensar), or make the election in the year’s last period.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when a refund-disposition export has no refund account on file.

When the determined disposition is a refund (devolución, D / V / X) the fichero must carry the cuenta-devolución block AEAT pays into — the IBAN, or the SWIFT-BIC plus foreign-bank block for a non-SEPA account. If the operator’s profile carries no refund account (no iban), the export REFUSES rather than emitting an empty or partial DID block: an empty refund block produces a devolución fichero AEAT cannot pay — a silent, defective filing. The fix is operator-driven: configure a refund account on the profile, or carry the credit forward (compensar) instead of requesting a refund. This is the no-silent-under-declaration sibling of the election’s eligibility refusal.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

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

Bases: ModeloError

Raised when the registry’s law-determined revision diverges from the work unit’s pinned revision.

This can only happen when the registry’s law-mapping was corrected after the work unit was created (the creation gate now enforces resolver-equality), or for work units persisted before the strengthened creation gate landed. The resolution is to re-create the work unit so its identity reflects the corrected law-determined revision.

Parameters:

  • message (str | None)

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

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]