Skip to content

Errors

openapi_first.errors

openapi_first.errors

Custom 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.

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.

MissingOperationHandler 

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

Bases: OpenAPIFirstError

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

This error occurs when: - An OpenAPI operation does not define an operationId, or - An operationId is defined but no matching function exists in the provided routes module.

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

Parameters

path : str The HTTP path declared in the OpenAPI specification.

str

The HTTP method (as declared in the OpenAPI spec).

str, optional

The operationId declared in the OpenAPI spec, if present.

OpenAPIFirstError

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

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.