Designing Exception APIs: Hierarchies, Interfaces, and Error Codes by Nikita Churikov | PyCon 2025

Exceptions are often treated as an afterthought—until logs fill with cryptic stack traces and developers resort to except Exception: everywhere. In this talk, we’ll treat exceptions as a first-class API surface. I’ll show how to design a clear exception hierarchy that distinguishes between user/validation errors, infrastructure failures, and unexpected bugs. We’ll explore how to define a lightweight interface (e.g. a status_code and optional metadata) so exceptions become predictable and machine-readable. Finally, we’ll see how stable domain error codes (like app.form.create.invalid_image_input) unlock better logging, monitoring, and user feedback. Attendees will leave with a practical pattern they can apply to any Python project—web service, CLI, or library. This isn’t just about catching errors: it’s about designing recoverable, observable, and maintainable systems where exceptions aren’t noise but meaningful signals. #pyconse #pyconse2025