Skip to content

5.15.0 — 2026-10-14

← 5.16.0 | 5.14.0 → | ↑ 5.x series

Added

Helpers - Errors

  • archipy.helpers.errors package - One home for error handling on both transports.
    • capture_exception, format_validation_errors, request_validation, invalid_argument_from_validation and resolve_error (maps any exception to the BaseError a client should see).
    • archipy.helpers.errors.fastapi: setup_exception_handlers, handle_fastapi_exception, handle_unexpected_exception, create_error_response and get_fastapi_exception_responses.
    • archipy.helpers.errors.grpc: GrpcExceptionInterceptor, abort_grpc and grpc_status_code.
  • GrpcExceptionInterceptor - One name for both kinds of server: GrpcExceptionInterceptor() is the sync interceptor and GrpcExceptionInterceptor(aio=True) the grpc.aio one. The sync and async variants share one error mapping instead of repeating it.
  • abort_grpc(error, context) - Replaces BaseError.abort_grpc_sync and abort_grpc_async. It detects a sync or grpc.aio context; on an async context use await abort_grpc(error, context).
  • validation_errors_as_internal - New keyword on AppUtils.create_grpc_app and create_async_grpc_app.

Changed

Behavior

  • gRPC validation errors - A Pydantic ValidationError raised by a gRPC handler is now reported as INVALID_ARGUMENT, the counterpart of the HTTP 422 the FastAPI handlers return. It used to be INTERNAL. Pass validation_errors_as_internal=True to keep the old mapping.
  • FastAPI handler - A BaseError handled through handle_fastapi_exception is now logged and recorded on the current OTel span, like the registered handlers already did.

Layout

  • Error handling moved - The FastAPI handlers left app_utils.py and the gRPC interceptor left helpers/interceptors/grpc/exception/. BaseError no longer imports grpc; http_status and grpc_status stay plain class attributes.
  • Removed (internal only) - FastAPIExceptionHandler, FastAPIUtils.setup_exception_handlers, GrpcServerExceptionInterceptor, AsyncGrpcServerExceptionInterceptor, BaseError.abort_grpc_sync, abort_grpc_async, abort_with_error_sync, abort_with_error_async, ErrorUtils.handle_grpc_exception, BaseUtils.format_validation_errors and archipy.models.dtos.fastapi_exception_response_dto. Apps that use AppUtils.create_fastapi_app, create_grpc_app and create_async_grpc_app are not affected.
  • Shared deprecation helper - deprecated_alias and warn_deprecated_name moved to archipy.helpers._deprecation.

Deprecated

  • BaseUtils.capture_exception - use archipy.helpers.errors.capture_exception.
  • BaseUtils.async_handle_fastapi_exception - use archipy.helpers.errors.fastapi.handle_fastapi_exception.
  • BaseUtils.get_fastapi_exception_responses - use archipy.helpers.errors.fastapi.get_fastapi_exception_responses.

Each emits a DeprecationWarning that names the replacement and returns the same result.

Tests

  • The gRPC validation scenarios in error_handling.feature now expect INVALID_ARGUMENT by default and INTERNAL with the opt-out. Test steps use the new archipy.helpers.errors paths.

Chore

  • Docs - New errors API reference page; the interceptors, utils, error handling and observability tutorials use the new paths.