Exception Reference

All OpenViper exceptions are defined in openviper.exceptions and form a single hierarchy rooted at OpenViperException. HTTP exceptions carry a status_code and are automatically converted to JSON error responses by the framework’s error handler.

Overview

The exception hierarchy is organized into five groups:

Configuration - raised during startup when settings are invalid.
HTTP - raised inside view handlers to return specific HTTP status codes.
ORM/Database - raised by the ORM layer on query errors.
Middleware - raised within the middleware pipeline.
AI - raised by the AI provider registry.

Exception Hierarchy

OpenViperException
├── ImproperlyConfigured
├── SettingsValidationError
├── HTTPException
│   ├── NotFound                 (404)
│   ├── MethodNotAllowed         (405)
│   ├── PermissionDenied         (403)
│   ├── Unauthorized             (401)
│   ├── ValidationError          (422)
│   ├── Conflict                 (409)
│   ├── TooManyRequests          (429)
│   ├── ServiceUnavailable       (503)
│   └── AuthenticationFailed     (401)
│       └── TokenExpired         (401)
├── ORMException
│   ├── DoesNotExist
│   ├── MultipleObjectsReturned
│   ├── IntegrityError
│   ├── TableNotFound
│   ├── QueryError
│   └── FieldError
├── MigrationError
├── MiddlewareException
└── AIException
    ├── ModelNotFoundError
    └── ModelCollisionError

Type Aliases

DetailValue

Type alias for values accepted by HTTPException detail parameter:

type DetailValue = str | dict[str, str | int] | list[dict[str, str | int]] | None

When None, the default detail phrase for the status code is used (resolved via HTTPException.default_detail()).

Key Exceptions

exception OpenViperException: Base exception for all OpenViper errors.

exception ImproperlyConfigured: Raised when the framework or application is incorrectly configured.

exception SettingsValidationError: Raised when settings fail validation on startup. Carries an errors list of human-readable messages.

exception HTTPException(status_code, detail=None, headers=None): Base HTTP error. Raise this (or a subclass) from any view to return a structured JSON error response with the given status code. detail accepts a DetailValue - a string, structured dict, list of dicts, or None. When None, the HTTP status phrase is used automatically via HTTPException.default_detail().

exception NotFound(detail='Not found.'): Returns 404 Not Found.

exception MethodNotAllowed(allowed): Returns 405 Method Not Allowed with an Allow header listing the permitted methods.

exception PermissionDenied(detail='Permission denied.'): Returns 403 Forbidden.

exception Unauthorized(detail='Authentication required.'): Returns 401 Unauthorized with WWW-Authenticate: Bearer.

exception ValidationError(errors): Returns 422 Unprocessable Entity. errors is a list[dict[str, str]] or dict[str, str] included verbatim in the response body.

exception Conflict(detail='Conflict.'): Returns 409 Conflict.

exception TooManyRequests(retry_after=None, detail=None): Returns 429 Too Many Requests. When retry_after is given the Retry-After header is set.

exception ServiceUnavailable(detail='Service unavailable.'): Returns 503 Service Unavailable.

exception AuthenticationFailed(detail='Invalid credentials.'): Returns 401 Unauthorized. Used by auth backends on credential failure.

exception TokenExpired: Subclass of AuthenticationFailed - raised when a JWT is expired.

exception ORMException: Base exception for all ORM and database errors.

exception DoesNotExist: Raised by the ORM when get() finds no matching record.

exception MultipleObjectsReturned: Raised by the ORM when get() matches more than one record.

exception IntegrityError: Raised when a database integrity constraint is violated.

exception TableNotFound(model_name, table_name): Raised when a model’s database table does not exist. Carries model_name and table_name attributes.

exception QueryError(detail='Invalid query.'): Raised when an ORM query is structurally invalid - for example, referencing a non-existent field or using a malformed filter expression.

exception FieldError(detail='Field does not exist.'): Raised when a referenced field does not exist on the model.

exception MigrationError: Raised when a migration cannot be applied or reversed.

exception MiddlewareException(detail='Middleware error.'): Raised within the middleware pipeline. Carries a detail attribute.

exception AIException: Base exception for all OpenViper AI errors.

exception ModelNotFoundError(model, available=None): Raised by ProviderRegistry when the requested model ID is not registered.

exception ModelCollisionError(model, existing_provider, new_provider): Raised when two AI providers try to claim the same model ID.

Example Usage

Raising HTTP Exceptions in Views

from openviper.exceptions import NotFound, PermissionDenied, ValidationError
from openviper.http.request import Request
from openviper.http.response import JSONResponse

async def get_post(request: Request, post_id: int) -> JSONResponse:
    post = await Post.objects.get_or_none(id=post_id)
    if post is None:
        raise NotFound(f"Post {post_id} does not exist.")
    if not post.is_published and not request.user.is_staff:
        raise PermissionDenied("You cannot view this post.")
    return JSONResponse(post._to_dict())

Handling ORM Exceptions

from openviper.exceptions import DoesNotExist

async def get_user(request):
    try:
        user = await User.objects.get(email="alice@example.com")
    except DoesNotExist:
        return JSONResponse({"error": "User not found"}, status_code=404)

Custom HTTP Exception

from openviper.exceptions import HTTPException

raise HTTPException(451, detail="Unavailable for legal reasons.")