Errors

openapi_first.errors

Summary

Exceptions for OpenAPI-first FastAPI applications.

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.