handling-errors - SKILL.md Agent Skill

name: Handling Errors description: Implement centralized error handling in Flask with custom exceptions, global handlers, and structured error responses.

Handling Errors

Goal

Build a centralized error handling system for a Flask API that uses custom exception classes, registers global error handlers, returns consistent JSON error responses, and logs errors with full request context.

When to Use

Setting up error handling in a new Flask API.
Replacing ad-hoc try/except blocks with a centralized pattern.
Adding structured error responses to an existing application.
Improving error logging and observability.
Onboarding to a codebase that needs consistent error treatment.

Instructions

Custom Exception Hierarchy

Define a base API exception and specific subclasses. Each exception carries a status code, an error code string, and an optional details payload.

# app/exceptions.py


class APIError(Exception):
    """Base exception for all API errors."""
    status_code = 500
    error_code = "INTERNAL_ERROR"
    message = "An unexpected error occurred."

    def __init__(self, message=None, details=None):
        super().__init__(message or self.message)
        self.message = message or self.message
        self.details = details

    def to_dict(self):
        payload = {
            "code": self.error_code,
            "message": self.message,
        }
        if self.details:
            payload["details"] = self.details
        return payload


class NotFoundError(APIError):
    status_code = 404
    error_code = "NOT_FOUND"
    message = "The requested resource was not found."


class ValidationError(APIError):
    status_code = 422
    error_code = "VALIDATION_ERROR"
    message = "The request data is invalid."


class AuthError(APIError):
    status_code = 401
    error_code = "AUTH_ERROR"
    message = "Authentication is required."


class ForbiddenError(APIError):
    status_code = 403
    error_code = "FORBIDDEN"
    message = "You do not have permission to perform this action."


class ConflictError(APIError):
    status_code = 409
    error_code = "CONFLICT"
    message = "The request conflicts with the current state of the resource."

Global Error Handler Registration

# app/error_handlers.py

import logging
from flask import jsonify, request, g
from app.exceptions import APIError

logger = logging.getLogger(__name__)


def register_error_handlers(app):
    """Register global error handlers on the Flask app."""

    @app.errorhandler(APIError)
    def handle_api_error(error):
        response = jsonify({"error": error.to_dict()})
        response.status_code = error.status_code

        logger.warning(
            "api_error",
            extra={
                "error_code": error.error_code,
                "status_code": error.status_code,
                "message": error.message,
                "path": request.path,
                "request_id": getattr(g, "request_id", None),
            },
        )

        return response

    @app.errorhandler(404)
    def handle_not_found(error):
        return jsonify({"error": {"code": "NOT_FOUND", "message": "Resource not found."}}), 404

    @app.errorhandler(405)
    def handle_method_not_allowed(error):
        return jsonify({"error": {"code": "METHOD_NOT_ALLOWED", "message": "Method not allowed."}}), 405

    @app.errorhandler(500)
    def handle_internal_error(error):
        logger.exception(
            "unhandled_exception",
            extra={
                "path": request.path,
                "method": request.method,
                "request_id": getattr(g, "request_id", None),
            },
        )
        return jsonify({"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred."}}), 500

Error Response Format

All error responses follow this structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request data is invalid.",
    "details": {
      "email": ["Not a valid email address."],
      "name": ["Missing data for required field."]
    }
  }
}

code is a machine-readable string that clients can switch on.
message is a human-readable summary.
details is optional and holds field-level or context-specific information.

Raising Exceptions in Application Code

Raise custom exceptions anywhere in the application. The global handler catches them.

from app.exceptions import NotFoundError, ValidationError


def get_user_or_404(user_id):
    user = User.query.get(user_id)
    if user is None:
        raise NotFoundError(f"User with id {user_id} not found.")
    return user


def create_user(data):
    if User.query.filter_by(email=data["email"]).first():
        raise ConflictError("A user with this email already exists.")
    user = User(**data)
    db.session.add(user)
    db.session.commit()
    return user

Logging Errors with Context

Always include the request ID, user identity (if available), and endpoint in error logs. For 500-level errors, use logger.exception() to capture the stack trace in logs without exposing it to the client.

logger.exception(
    "unhandled_exception",
    extra={
        "request_id": getattr(g, "request_id", None),
        "user_id": getattr(g, "current_user_id", None),
        "endpoint": request.endpoint,
        "method": request.method,
        "path": request.path,
    },
)

Wiring It Into create_app()

from app.error_handlers import register_error_handlers


def create_app(config_name=None):
    app = Flask(__name__)
    app.config.from_object(config_by_name[config_name or "development"])

    register_error_handlers(app)

    # ... extensions, blueprints, middleware

    return app

Constraints

✅ Do

Use custom exception classes that inherit from a common APIError base.
Register global error handlers for APIError, 404, 405, and 500.
Return consistent JSON error responses with code, message, and optional details.
Log all 500-level errors with logger.exception() to capture stack traces.
Include the request ID and endpoint in error log context.
Use specific exception subclasses (NotFoundError, ValidationError) instead of generic exceptions.

❌ Don't

Do not catch bare Exception in route handlers; let errors propagate to the global handler.
Do not expose stack traces or internal error details to API clients.
Do not return HTML error pages from an API; always return JSON.
Do not silently swallow exceptions without logging.
Do not return 200 status codes for errors.
Do not use generic error messages that give no indication of what went wrong.

Output Format

Generate app/exceptions.py and app/error_handlers.py as separate files. Show the updated create_app() with register_error_handlers(app) called.

Dependencies

Scaffolding Flask -- app factory where error handlers are registered.
Building API Routes -- routes that raise these custom exceptions.