Quickstart

Install with pip

pip install drf-standardized-errors

Add drf-standardized-errors to your installed apps

INSTALLED_APPS = [
    # other apps
    "drf_standardized_errors",
]

Set the exception handler for all API views

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

or on a view basis (especially if you’re introducing this to a versioned API)

from drf_standardized_errors.handler import exception_handler
from rest_framework.views import APIView

class MyAPIView(APIView):
    def get_exception_handler(self):
        return exception_handler

Now, your API error responses for 4xx and 5xx errors, will look like this

{
  "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"
    }
  ]
}

or

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

Important Notes

• 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}

• Cases where you explicitly return a response with a 4xx or 5xx status code in your APIView do not go through the exception handler and thus, will not have the standardized error format. So, we recommend that you raise an exception with raise APIException("Service temporarily unavailable.", code="service_unavailable") instead of return Response(data, status=500). That way, error response formatting is handled automatically for you. But, keep in mind that exceptions that result in 5xx response are reported to error monitoring tools (like Sentry) if you’re using one.

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.