Errors in Programming: An Unavoidable Reality

In programming, errors are the only certainty. Whether you’re coding something simple or complex, whether it’s a ten-line script or an enterprise application, there’s always a risk something will go wrong. That’s why we’re destined to create our own exceptions. They help us better describe what happened, provide users with information, and make testing and debugging easier.

Working with code that throws appropriate exceptions in specific situations is much more efficient. It’s worth adopting principles that improve our workflow, simplify error detection, and make it easier to understand what’s happening in the system. Error handling is an integral part of our job—APIs might fail to respond, clients might not deliver something, or inputs might be invalid. So, how do we handle exceptions so they don’t overwhelm us, are helpful, and most importantly, allow us to code faster?

One to Rule Them All…

I used to handle exceptions directly in views. Out of laziness, it seemed convenient. Today, I know it was the wrong approach. If someone had told me about a better way earlier, I could have saved myself a lot of trouble.

Now, I believe every system should have one place for exception handling. This should be designed so that caught exceptions can generate appropriate logs in the application and return information to the user. Centralization:

• Saves time by eliminating the need to write handling logic in every controller.
• Simplifies managing messages returned to users depending on the exception type.
• Enables logging and tracking exceptions in one place.

This is a well-known practice, but what if we take it a step further? A single exception-handling location that behaves based on how the exception was raised? For this, we need two abstractions.

Middleware or Exception Handler

A central location that catches all exceptions and generates a response for the user. Below is an example for the django-ninja framework:

@api.exception_handler(Exception)
def api_exception_handler(request, exc):
    """
    Handles exceptions raised in API requests.

    - If the exception is an instance of `ApiException`, it sends a response with a
      user-friendly error message and a specific HTTP status code.
    - For other exceptions, it logs the exception details for debugging and
      provides a generic error response.

    :param request: The incoming request object.
    :param exc: The raised exception.
    :return: A JSON response containing the error message and status code.
    """

    if isinstance(exc, ApiException):
        return api.create_response(
            request,
            {"message": exc.api_client_message},
            status=exc.status_code,
        )
    else:
        logger.exception(exc)
        return api.create_response(
            request,
            {"message": "An unexpected error occurred. Please try again later."},
            status=500,
        )

As shown, a simple check determines if the exception inherits from our abstract class. If it does, information in the exception is used to build the response.

Exception Abstraction

I create a base exception class, e.g., ApiException, allowing you to define attributes like HTTP status and a client message. This lets you raise an exception anywhere in the code, providing users with appropriate information—simple, fast, and efficient:

class ApiException(Exception):
    """
    Exception created to automatically handle proper messages for clients.
    When raised, the handler creates a 400 status and supplies the message
    from the `api_client_message` attribute.
    """

    _status_code = 400
    _api_client_message = "Error occurred. Try again."

    def __init__(self, message: str = None, api_client_message: str = None,
                 status_code: int = None):
        # Use class data if no constructor data is provided
        exception_message = message if message else self._api_client_message
        super().__init__(exception_message)

        self._status_code = status_code if status_code else self._status_code
        self._api_client_message = api_client_message if api_client_message else self._api_client_message

        message_format = f"{self.__class__.__name__} raised: {message}"

        # Log error message
        if status.is_client_error(self._status_code):
            logger.warning("Warning: " + message_format)
        if status.is_server_error(self._status_code):
            logger.error("Error: " + message_format)

    @property
    def api_client_message(self) -> str:
        return self._api_client_message

    @property
    def status_code(self) -> int:
        return self._status_code

Additionally, during exception instantiation, I can decide whether to use predefined data or create custom data. Logging for monitoring purposes is also included, recording events based on exception levels.

This example is specific to API exceptions, hence its tight integration with HTTP statuses. You can create your own statuses or exception types and translate them into appropriate responses.

…And Bind Them in ExceptionRegistry

An exception hierarchy is key to clear error management. Exceptions may inherit from a parent class to narrow scope and ease identification. Still, exceptions multiply. How do you handle a growing list of options?

Avoid over-complication. Create basic exceptions that make sense and provide clear, objective information about what happened in the system. For example, a "Database Connection Error" is sufficient if it clearly identifies the issue. Over-detailing exceptions can lead to confusion.

To prevent forgetfulness—an issue I often face when managing numerous exceptions—I recommend creating an * ExceptionRegistry*. This organizes exceptions and acts as a reference point:

• Quickly find the appropriate exception.
• Easily categorize exceptions by module, application, or domain.
• Avoid duplicates differing only in minor details.

For instance, instead of creating numerous exceptions for each API call failure, stick to a base exception and define details when raising it. Use an ExceptionRegistry to keep all exceptions accessible:

class ExceptionRegistry:
    """
    A centralized registry for managing custom exceptions used throughout the application.

    Attributes:
        - Direct access to predefined exceptions.
        - Organized by functionality, domain, or module.
    """

    API_EXCEPTION = ApiException
    PERMISSION_DENIED = PermissionDenied
    ALREADY_EXISTS = AlreadyExists
    TOKEN_UNDECODED = TokenUnDecodedException
    TOKEN_EXPIRED = TokenExpired
    EXTERNAL_AUTH_EXCEPTION = ExternalAuthException
    NOT_AUTHENTICATED = NotAuthenticated
    DOES_NOT_EXIST = DoesNotExist
    NOT_FROM_SAME_ORGANIZATION = NotFromSameOrganizationException
    CUSTOMER_DOES_NOT_EXIST = CustomerDoesNotExist
    CART_DOES_NOT_EXIST = CartDoesNotExist
    REDIRECT_EXCEPTION = ApiRedirectException
    ...

While simplicity is key, having one location for all exceptions is a clear, fast, and elegant solution to avoid drowning in a sea of options.

Summary

The exception-handling approach I’ve outlined provides a structured and efficient way to code. Centralizing exception handling eliminates chaos, saves time, and allows focus on business value. When defining exceptions, you can think through the message to convey to users and the information to log. This makes your code more maintainable and your application easier to manage.

Alex