app.errors

Domain exception classes and their FastAPI handler registration.

Domain errors are plain Python exceptions raised by the service layer. Routers never translate built-in exceptions (ValueError, KeyError) into HTTP responses; instead every error condition that can cross a layer boundary gets its own exception class here, mapped to an explicit HTTP status code by a registered handler.

Error bodies are {"detail": "<message>"}; errors constructed with a machine-readable code add "code": "<code>" next to it (the authentication and authorization errors always do). An optional hint (what the caller or an operator can do about it) adds "hint": "<hint>", and extra adds further JSON members (for example the issues list of a refused candidate document).

exception app.errors.AdrianoError(message, *, code=None, hint=None, extra=None)

Bases: Exception

Base class for all domain exceptions raised by the services.

Parameters:

  • message (str) – Human-readable description of the error.

  • code (str | None) – Optional machine-readable error code.

  • hint (str | None) – Optional recovery advice for the caller or operator.

  • extra (Mapping[str, JsonValue] | None) – Optional further JSON members of the error body.

body()

Build the JSON error body.

Return type:

dict[str, JsonValue]

Returns:

detail plus code/hint when set, plus extra.

property headers: Mapping[str, str]

Extra response headers for this error.

Returns:

Header names and values (none by default).

exception app.errors.ConfigurationError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

Raised when catalog.yaml or a related setting is invalid.

exception app.errors.NotFoundError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

Raised when a requested catalog resource does not exist.

exception app.errors.ConflictError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

Raised when a write conflicts with existing state (HTTP 409).

exception app.errors.DecisionExistsError(message, *, code=None, hint=None, extra=None)

Bases: ConflictError

Raised when the identity already has a decision for the digest.

exception app.errors.CandidateExistsError(message, *, code=None, hint=None, extra=None)

Bases: ConflictError

Raised when a create-only candidate write finds an existing row.

exception app.errors.DeliveryExistsError(message, *, code=None, hint=None, extra=None)

Bases: ConflictError

Raised when an intake run with the same delivery id exists.

exception app.errors.ForbiddenError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

Raised when the caller lacks permission for an action.

exception app.errors.ValidationFailedError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

Raised when submitted content fails validation (HTTP 422).

exception app.errors.PayloadTooLargeError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

Raised when a request body or document exceeds a limit (HTTP 413).

exception app.errors.AuthenticationError(message, *, code, token_presented=True, hint=None)

Bases: AdrianoError

Raised when a request has no acceptable bearer token (HTTP 401).

The response carries WWW-Authenticate: Bearer (RFC 6750), with error="invalid_token" when a token was presented.

Parameters:

  • message (str) – Human-readable reason (never contains the token).

  • code (str) – Machine-readable error code.

  • token_presented (bool) – Whether the request carried a token.

property headers: Mapping[str, str]

Build the WWW-Authenticate challenge.

Returns:

The challenge header.

exception app.errors.AuthUnavailableError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

Raised when the server cannot authenticate anyone (HTTP 503).

Either no authentication mechanism is configured, or the identity provider’s discovery document or keys cannot be fetched.

app.errors.register_handlers(app)

Register exception handlers for every domain error class.

Parameters:

app (FastAPI) – The FastAPI application under construction.

Return type:

None