drf-standardized-errors

DRF Standardized Errors

Standardize your DRF API error responses.

By default, the package will convert all API error responses (4xx and 5xx) to the following standardized format:

{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "detail": "This field is required.",
      "attr": "name"
    },
    {
      "code": "max_length",
      "detail": "Ensure this value has at most 100 characters.",
      "attr": "title"
    }
  ]
}

{
  "type": "client_error",
  "errors": [
    {
      "code": "authentication_failed",
      "detail": "Incorrect authentication credentials.",
      "attr": null
    }
  ]
}

{
  "type": "server_error",
  "errors": [
    {
      "code": "error",
      "detail": "A server error occurred.",
      "attr": null
    }
  ]
}

Features

• Highly customizable: gives you flexibility to define your own standardized error responses and override specific aspects the exception handling process without having to rewrite everything.
• Supports nested serializers and ListSerializer errors
• Plays nicely with error monitoring tools (like Sentry, ...)

Requirements

• python >= 3.8
• Django >= 3.2
• DRF >= 3.12

Quickstart

Install with pip

pip install drf-standardized-errors

Add drf-standardized-errors to your installed apps

INSTALLED_APPS = [
    # other apps
    "drf_standardized_errors",
]

Register the exception handler

REST_FRAMEWORK = {
    # other settings
    "EXCEPTION_HANDLER": "drf_standardized_errors.handler.exception_handler"
}

Notes

• This package is a DRF exception handler, so it standardizes errors that reach a DRF API view. That means it cannot handle errors that happen at the middleware level for example. To handle those as well, you can customize the necessary django error views. You can find more about that in this issue.

• Standardized error responses when DEBUG=True for unhandled exceptions are disabled by default. That is to allow you to get more information out of the traceback. You can enable standardized errors instead with:

DRF_STANDARDIZED_ERRORS = {"ENABLE_IN_DEBUG_FOR_UNHANDLED_EXCEPTIONS": True}

Integration with DRF spectacular

If you plan to use drf-spectacular to generate an OpenAPI 3 schema, install with pip install drf-standardized-errors[openapi]. After that, check the doc page for configuring the integration.

Links

• Documentation: https://drf-standardized-errors.readthedocs.io/en/latest/
• Changelog: https://github.com/ghazi-git/drf-standardized-errors/releases
• Code & issues: https://github.com/ghazi-git/drf-standardized-errors
• PyPI: https://pypi.org/project/drf-standardized-errors/

License

This project is MIT licensed.