Errors

openapi_first.errors

Exceptions for OpenAPI-first FastAPI applications.

Summary

This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.

Notes

Design Principles:

- Errors represent programmer mistakes, not runtime conditions
- All errors are raised during application startup
- Messages are actionable and suitable for CI/CD output
- Exceptions are explicit rather than reused from generic built-ins

These errors should normally cause immediate application failure.

Classes

MissingOperationHandler

MissingOperationHandler(*, path: str, method: str, operation_id: Optional[str] = None)

Bases: OpenAPIFirstError

Raised when an OpenAPI operation cannot be resolved to a handler.

Notes

Scenarios:

- An OpenAPI operation does not define an operationId
- An operationId is defined but no matching function exists in the provided routes module

Guarantees:

- This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync

Initialize the error.

Parameters:

Name	Type	Description	Default
`path`	`str`	The HTTP path declared in the OpenAPI specification.	required
`method`	`str`	The HTTP method (as declared in the OpenAPI spec).	required
`operation_id`	`str`	The operationId declared in the OpenAPI spec, if present.	`None`

Functions

OpenAPIFirstError

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

Notes

Responsibilities:

- This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors
- All exceptions raised by the OpenAPI-first core should inherit from this type