django-error-handler

A reusable Django REST Framework package that provides a unified, structured, and multilingual error handling system.

Instead of returning inconsistent error responses from different parts of your application, django-error-handler ensures every API error follows the same format, making your backend predictable, maintainable, and frontend-friendly.

---

Features

• Unified API error response format
• Centralized exception handling
• Built-in support for Django REST Framework exceptions
• Multilingual error messages
• Custom error code mapping
• Consistent validation error responses
• Custom JSON renderer
• Production-ready logging for unexpected exceptions
• Easy integration with existing DRF projects

---

Why?

Default Django and DRF error responses can vary depending on where the exception originates:

{
    "detail": "Not found."
}

{
    "username": [
        "This field is required."
    ]
}

{
    "non_field_errors": [
        "Unable to log in."
    ]
}

This inconsistency makes frontend development more difficult.

django-error-handler standardizes everything into a single predictable structure:

{
    "success": false,
    "code": "validation_error",
    "message": "Validation failed.",
    "errors": {
        "email": [
            "This field is required."
        ]
    }
}

---

Response Structure

Success Response

{
    "id": 1,
    "name": "John Doe"
}

Error Response

{
    "success": false,
    "code": "not_found",
    "message": "Requested resource was not found.",
    "errors": {
        "detail": "Not found."
    }
}

---

Supported Exceptions

Exception	Error Code
NotFound	not_found
PermissionDenied	permission_denied
AuthenticationFailed	authentication_failed
NotAuthenticated	not_authenticated
ValidationError	validation_error
ParseError	parse_error
MethodNotAllowed	method_not_allowed
Throttled	throttled
NotAcceptable	not_acceptable
UnsupportedMediaType	unsupported_media_type

---

Installation

pip install django-error-handler

---

Configuration

settings.py

REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": "django_error_handler.handlers.custom_exception_handler",
    "DEFAULT_RENDERER_CLASSES": [
        "django_error_handler.handlers.CustomJSONRenderer",
    ],
}

---

Multilingual Messages

One of the key features of this package is centralized message management.

You can define all error messages in a dedicated file and easily provide translations for multiple languages.

Example:

ERROR_MESSAGES = {
    "en": {
        "not_found": (
            "not_found",
            "Resource not found",
            404
        ),
    },
    "fa": {
        "not_found": (
            "not_found",
            "منبع مورد نظر پیدا نشد",
            404
        ),
    }
}

This allows APIs to return localized and user-friendly messages without changing business logic.

---

Validation Error Handling

Field-level validation errors are automatically normalized.

Input:

raise ValidationError({
    "email": ["This field is required."]
})

Output:

{
    "success": false,
    "code": "validation_error",
    "message": "Validation failed.",
    "errors": {
        "email": [
            "This field is required."
        ]
    }
}

---

Unexpected Exceptions

Unhandled exceptions are automatically:

• Logged using Python logging
• Converted into a consistent API response
• Hidden behind a generic server error message

Example:

{
    "success": false,
    "code": "server_error",
    "message": "Internal server error.",
    "errors": {
        "detail": "Database connection failed"
    }
}

---

Example Output

{
    "success": false,
    "code": "authentication_failed",
    "message": "Authentication failed.",
    "errors": {
        "detail": "Invalid token."
    }
}

---

Benefits

• Cleaner frontend integration
• Consistent API contracts
• Easier debugging
• Better developer experience
• Internationalization support
• Reusable across multiple projects

---

Roadmap

• Language auto-detection
• Custom exception registration
• OpenAPI integration
• Error tracking integrations (Sentry, LogRocket)
• Package-level settings management

---

License

MIT License

---

Built for Django REST Framework applications that require predictable, scalable, and multilingual API error handling.