How to design a clean error-handling strategy in Python?

[jynamba]

In my project, error handling is inconsistent. Sometimes I just print, sometimes I use try/except, and sometimes I re-raise exceptions. Example:

def process_user(data):
    try:
        user_id = int(data["id"])
    except Exception:
        print("Invalid user ID")

Problems:

• Hard to debug when something goes wrong.
• No consistent error messages.
• Don’t know when to use custom exceptions.

Questions:

1. Should I create custom exception classes for different errors (e.g., ValidationError, DatabaseError)?
2. How do I balance between catching specific errors and avoiding too much boilerplate?
3. What’s the best way to log errors (print, logging module, or external services like Sentry)?
4. Is there a standard error-handling pattern used in production Python apps?

[dtoyoda2025]

Error handling is one of those things that can make or break the maintainability of a Python project. A few best practices:

---

1. Use Specific Exceptions Instead of Bare except:

Catching everything makes debugging harder. Always catch the exact exception you expect:

try:
    user_id = int(data["id"])
except KeyError:
    raise ValidationError("Missing required field: id")
except ValueError:
    raise ValidationError("User ID must be a number")

This way, you know exactly what went wrong.

---

2. Create Custom Exceptions for Your Domain

Defining custom exceptions helps keep errors meaningful and consistent across the project:

class AppError(Exception):
    """Base class for all custom errors"""

class ValidationError(AppError):
    """Raised when input data is invalid"""

class DatabaseError(AppError):
    """Raised when DB operations fail"""

Now your code can raise domain-specific errors that are easy to catch later.

---

3. Centralize Error Handling Where Possible

Instead of sprinkling try/except everywhere, centralize it at the entry points of your app (like API routes, CLI commands, or worker loops).

Example in a FastAPI app:

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.exception_handler(ValidationError)
async def validation_handler(request, exc: ValidationError):
    return JSONResponse(status_code=400, content={"error": str(exc)})

This keeps business logic clean while still giving users proper error messages.

---

4. Always Log Errors

Use the logging module (instead of print) so you can control log levels and send logs to files or services like Sentry.

import logging

logger = logging.getLogger(__name__)

try:
    result = db.query("SELECT * FROM users")
except Exception as e:
    logger.exception("Database query failed")
    raise DatabaseError from e

logger.exception automatically includes the stack trace, which is super useful for debugging.

---

5. Decide When to Handle vs. Propagate

• Handle locally → if you can recover (e.g., retrying a network request).
• Propagate upwards → if you can’t recover (e.g., DB is down). Use raise to let higher-level code decide.