qfa.domain.errors#

Domain error hierarchy for the feedback analysis backend.

Exceptions

`AnalysisError`	Non-recoverable error during feedback analysis.
`AnalysisTimeoutError`	Raised when an analysis exceeds the allowed deadline.
`AuthenticationError`	Raised when an API request cannot be authenticated.
`AuthorizationError`	Raised when a user lacks permission for the requested operation.
`DomainError`	Base error for all domain-level exceptions.
`FeedbackTooLargeError`(message, *, ...)	Raised when estimated tokens for the submitted feedback exceed the limit.
`KeyAlreadyExistsError`	Raised when we try to create a key with an existing id.
`KeyNotFoundError`	Raised when we try to access a key that doesn't exist.
`LLMBadRequestError`(message, *[, provider_status])	Raised when the LLM provider returns a 400 Bad Request response.
`LLMContentPolicyViolationError`(message, *[, ...])	Raised when the LLM provider rejects the request due to content policy.
`LLMError`(message, *[, provider_status])	Base error for LLM adapter failures.
`LLMRateLimitError`(message, *[, ...])	Raised when the LLM provider returns a rate-limit response.
`LLMResponseParseError`(message, *[, ...])	Raised when a structured LLM response fails schema validation.
`LLMTimeoutError`(message, *[, provider_status])	Raised when the LLM provider does not respond in time.
`MissingCallScopeError`	Raised when an LLM call is recorded without an active CallContext.
`PromptInjectionDetectedError`	Raised when input matches a known prompt-injection pattern.
`TenantDoesNotAllowSuperUsersError`	Raised when an operation requires superuser privileges but the tenant does not allow superusers.
`TenantNotFoundError`	Raised when we try to access a tenant that doesn't exist.
`UsageRepositoryUnavailableError`	Raised when a usage-repository read fails due to backend unavailability.

exception qfa.domain.errors.DomainError[source]#

Bases: Exception

Base error for all domain-level exceptions.

exception qfa.domain.errors.AnalysisError[source]#

Bases: DomainError

Non-recoverable error during feedback analysis.

exception qfa.domain.errors.AnalysisTimeoutError[source]#

Bases: AnalysisError

Raised when an analysis exceeds the allowed deadline.

exception qfa.domain.errors.PromptInjectionDetectedError[source]#

Bases: AnalysisError

Raised when input matches a known prompt-injection pattern.

Sole raiser: LiteLLMClient._check_injection.

exception qfa.domain.errors.FeedbackTooLargeError(message: str, *, estimated_tokens: int, limit: int)[source]#

Bases: AnalysisError

Raised when estimated tokens for the submitted feedback exceed the limit.

Variables:

estimated_tokens (int) – The estimated token count for the submitted feedback records.
limit (int) – The maximum allowed token count.

exception qfa.domain.errors.LLMError(message: str, *, provider_status: int | None = None)[source]#

Bases: DomainError

Base error for LLM adapter failures.

provider_status is a classified scalar (the provider’s HTTP status code), never free text — see ADR-018. None means the provider did not expose a usable status code.

exception qfa.domain.errors.LLMTimeoutError(message: str, *, provider_status: int | None = None)[source]#

Bases: LLMError

Raised when the LLM provider does not respond in time.

exception qfa.domain.errors.LLMBadRequestError(message: str, *, provider_status: int | None = None)[source]#

Bases: LLMError

Raised when the LLM provider returns a 400 Bad Request response.

exception qfa.domain.errors.LLMContentPolicyViolationError(message: str, *, provider_status: int | None = None, category: str | None = None, severity: str | None = None, discarded_prompt_tokens: int = 0, discarded_completion_tokens: int = 0, discarded_cost: float = 0.0)[source]#

Bases: LLMBadRequestError

Raised when the LLM provider rejects the request due to content policy.

category and severity are Azure’s content-filter annotation (e.g. "violence" / "high") when the rejection was detected from a completed response’s content_filter_results rather than sniffed from a BadRequestError message — a closed, low-cardinality set of classified scalars, never free text (see ADR-018). Both are None when unavailable.

discarded_prompt_tokens, discarded_completion_tokens and discarded_cost carry usage billed by the provider on retried attempts that were discarded because the response was blocked — Azure’s asynchronous filter generates (and bills) a completion before rejecting it. They are the cumulative total across every discarded attempt for this call, so a caller recording usage from this exception still accounts for the real spend even though no LLMResponse was ever returned. Zero when the rejection carried no billable usage (e.g. the synchronous, pre-generation rejection path).

exception qfa.domain.errors.LLMRateLimitError(message: str, *, provider_status: int | None = None, retry_after: int | None = None)[source]#

Bases: LLMError

Raised when the LLM provider returns a rate-limit response.

retry_after is the provider’s Retry-After value in seconds. None means the provider gave no usable header.

exception qfa.domain.errors.LLMResponseParseError(message: str, *, provider_status: int | None = None)[source]#

Bases: LLMError

Raised when a structured LLM response fails schema validation.

Distinct from other LLMError cases (timeouts, missing content, provider failures) so callers may choose to treat malformed model output as an empty/absent result instead of failing the request.

exception qfa.domain.errors.AuthenticationError[source]#

Bases: DomainError

Raised when an API request cannot be authenticated.

exception qfa.domain.errors.AuthorizationError[source]#

Bases: DomainError

Raised when a user lacks permission for the requested operation.

exception qfa.domain.errors.TenantDoesNotAllowSuperUsersError[source]#

Bases: DomainError

Raised when an operation requires superuser privileges but the tenant does not allow superusers.

exception qfa.domain.errors.KeyAlreadyExistsError[source]#

Bases: DomainError

Raised when we try to create a key with an existing id.

exception qfa.domain.errors.KeyNotFoundError[source]#

Bases: DomainError

Raised when we try to access a key that doesn’t exist.

exception qfa.domain.errors.TenantNotFoundError[source]#

Bases: DomainError

Raised when we try to access a tenant that doesn’t exist.

exception qfa.domain.errors.MissingCallScopeError[source]#

Bases: RuntimeError

Raised when an LLM call is recorded without an active CallContext.

Indicates a wiring bug: the driving adapter forgot to enter a call_scope block before calling the LLM. Should never reach a user.

exception qfa.domain.errors.UsageRepositoryUnavailableError[source]#

Bases: DomainError

Raised when a usage-repository read fails due to backend unavailability.

This signals that the repository is wired and the request hit the DB but the connection or query failed transiently (e.g. Postgres unreachable, pool exhausted, broker reset). The API surfaces this as 503 {"code": "usage_backend_unavailable"}.