exceptions.rst

Exception Handling

Connexion allows you to register custom error handlers to convert Python Exceptions into HTTP problem responses.

You can register error handlers on:

• The exception class to handle If this exception class is raised somewhere in your application or the middleware stack, it will be passed to your handler.
• The HTTP status code to handle Connexion will raise starlette.HTTPException errors when it encounters any issues with a request or response. You can intercept these exceptions with specific status codes if you want to return custom responses.

AsyncApp

from connexion import AsyncApp
from connexion.lifecycle import ConnexionRequest, ConnexionResponse

def not_found(request: ConnexionRequest, exc: Exception) -> ConnexionResponse:
    return ConnexionResponse(status_code=404, body=json.dumps({"error": "NotFound"}))

app = AsyncApp(__name__)
app.add_error_handler(FileNotFoundError, not_found)
app.add_error_handler(404, not_found)

View a detailed reference of the add_error_handler method

connexion.AsyncApp.add_error_handler

FlaskApp

from connexion import FlaskApp
from connexion.lifecycle import ConnexionRequest, ConnexionResponse

def not_found(request: ConnexionRequest, exc: Exception) -> ConnexionResponse:
    return ConnexionResponse(status_code=404, body=json.dumps({"error": "NotFound"}))

app = FlaskApp(__name__)
app.add_error_handler(FileNotFoundError, not_found)
app.add_error_handler(404, not_found)

View a detailed reference of the add_error_handler method

connexion.FlaskApp.add_error_handler

Note

Warning

⚠️ The following is not recommended as it complicates the exception handling logic,

You can also register error handlers on the underlying flask application directly.

flask_app = app.app
flask_app.register_error_handler(FileNotFoundError, not_found)
flask_app.register_error_handler(404, not_found)

Flask documentation

Error handlers registered this way:

• Will only intercept exceptions thrown in the application, not in the Connexion middleware.
• Can intercept exceptions before they reach the error handlers registered on the connexion app.
• When registered on status code, will intercept only werkzeug.exceptions.HTTPException thrown by werkzeug / Flask not starlette.exceptions.HTTPException.

ConnexionMiddleware

from asgi_framework import App
from connexion import ConnexionMiddleware
from connexion.lifecycle import ConnexionRequest, ConnexionResponse

def not_found(request: ConnexionRequest, exc: Exception) -> ConnexionResponse:
    return ConnexionResponse(status_code=404, body=json.dumps({"error": "NotFound"}))

app = App(__name__)
app = ConnexionMiddleware(app)

app.add_error_handler(FileNotFoundError, not_found)
app.add_error_handler(404, not_found)

View a detailed reference of the add_error_handler method

connexion.ConnexionMiddleware.add_error_handler

Note

This might not catch HTTPExceptions with the same status code raised by your wrapped ASGI/WSGI framework.

Note

Error handlers can be async coroutines as well.

Default Exception Handling

By default connexion exceptions are JSON serialized according to Problem Details for HTTP APIs

Application can return errors using connexion.problem.problem or raise exceptions that inherit either from connexion.ProblemException or one of its subclasses to achieve the same behavior.

Using this, we can rewrite the handler above:

from connexion.lifecycle import ConnexionRequest, ConnexionResponse
from connexion.problem import problem

def not_found(request: ConnexionRequest, exc: Exception) -> ConnexionResponse:
    return problem(
        title="NotFound",
        detail="The requested resource was not found on the server",
        status=404,
    )

View a detailed reference of the problem function

connexion.problem.problem

Connexion Exceptions

There are several exception types in connexion that contain extra information to help you render appropriate messages to your user beyond the default description and status code:

connexion.exceptions