error-handling_skill

Overview

This skill provides practical error handling patterns for Python backends using FastAPI, Pydantic, and asyncio. It embraces the “Let it crash” philosophy: raise specific domain exceptions where errors occur and convert them to safe HTTP responses at application boundaries. The guidance covers domain exceptions, global handlers, validation errors, async background failures, and preventing stack trace leakage.

How this skill works

Define semantic domain exceptions and a consistent error response schema with Pydantic. Let exceptions bubble up from services and routes, then register FastAPI exception handlers to transform exceptions into JSON responses and safe status codes. Wrap third-party SDK errors into domain errors, log full tracebacks in a single generic handler, and run background tasks inside safe wrappers to capture and report failures.

When to use it

• Designing API error responses and consistent error schemas
• Handling RequestValidationError and preventing validation leaks
• Managing exceptions in async code and background tasks
• Creating custom exception hierarchies for domain semantics
• Wrapping third-party SDK failures and implementing retries

Best practices

• Raise low, catch high: throw in domain code, handle at API boundaries
• Create domain-specific exceptions with error codes and status codes
• Register centralized exception handlers (@app.exception_handler) for DomainError, HTTPException, validation and generic errors
• Never use bare except; catch specific exceptions and preserve original context with raise ... from
• Log full tracebacks internally and return minimal, safe messages to clients
• Wrap background tasks with try/except to log and send failures to DLQ/alerts

Example use cases

• Return a 404 JSON error via UserNotFoundError instead of returning None
• Convert Pydantic RequestValidationError into a 422 structured response without leaking details
• Wrap httpx failures in ExternalServiceError and retry transient failures with tenacity
• Add a global Exception handler to ensure no stack traces reach clients
• Run email sending in a safe_background_task that logs failures and posts to a dead-letter queue