DRF Standardized Errors

DRF Standardized Errors replaces Django REST Framework’s default exception handler with one that normalizes every 4xx/5xx response — validation errors, authentication failures, nested serializer errors, unhandled server exceptions — into a single, predictable {type, errors: [{code, detail, attr}]} envelope. Instead of clients having to branch on DRF’s inconsistent native error shapes (a flat list for some errors, nested dicts for others), every error type collapses into the same array of code/detail/attr objects.

The package is built for customization rather than being an opinionated black box: every step of exception-to-response conversion (exception formatting, error building, response building) is a swappable class, so teams can override just the pieces they need — a custom error code, a different top-level type, or integration with error-monitoring tools like Sentry — without reimplementing the whole handler.

What You Get

• A drop-in EXCEPTION_HANDLER setting that standardizes validation, authentication, permission, throttling, and unhandled server errors into one response shape
• Support for nested serializers and ListSerializer errors, correctly flattening attr paths (e.g. line_items.0.quantity) that DRF’s default handler mangles
• A pluggable class-based pipeline (ExceptionFormatter, ErrorResponse) so any step of exception handling can be overridden without forking the package
• Built-in drf-spectacular integration that documents the standardized error schema automatically in generated OpenAPI specs
• Compatibility hooks for error-monitoring tools like Sentry so standardized errors still surface correctly in exception tracking

Common Use Cases

• Giving frontend/mobile clients one predictable error shape to parse instead of branching on DRF’s per-exception response formats
• Documenting a DRF API’s error responses consistently in OpenAPI/Swagger via the drf-spectacular integration
• Flattening and reporting validation errors from deeply nested serializers (nested objects, list serializers) in a client-friendly structure
• Standardizing 500-level error responses across a DRF API so unhandled exceptions don’t leak inconsistent tracebacks or shapes to clients

Under The Hood

Architecture - The package registers a single exception_handler function as DRF’s EXCEPTION_HANDLER setting; internally it delegates to an ExceptionFormatter class that walks the raised exception (including nested serializer ValidationError trees) and produces a list of ErrorResponse objects, which a final ExceptionHandler class assembles into the standardized {type, errors} JSON body and HTTP status code.

Tech Stack - Pure Python targeting Django 3.2+ and DRF 3.12+, with an optional integration module for drf-spectacular that hooks into its schema-generation extension points to document the standardized error format automatically.

Code Quality - The repository has CI-enforced tests (GitHub Actions tests.yml) with Codecov coverage reporting, black code-style enforcement, and Read the Docs-hosted documentation, indicating an actively maintained, test-driven codebase rather than a thin wrapper.

API Design - Integration requires only a settings change (EXCEPTION_HANDLER plus INSTALLED_APPS entry) for the default behavior, while customization is done by subclassing well-named classes (ExceptionFormatter, ErrorResponse) and pointing settings at the subclass — a low floor for adoption with a clear escape hatch for teams needing non-default error shapes.