Django Rest Framework Simple API Errors

What is this?

A library for Django Rest Framework returning consistent, predictable and easy-to-parse API error messages.

This library was built with RFC7807 guidelines in mind, but with a small twist: it defines a "problem detail" as a list instead of a string, but it still serves as a way to include errors in a human-readable and easy-to-parse format for any API consumer. Error messages are formatted using RFC7807 keywords and DRF exception data.

Unlike standard DRF, where the error response format varies depending on the error source, this library always returns errors in a consistent and predictable structure.

What's different?

Compared to other similar and popular libraries, this library:

• Is based on RFC7807 guidelines
• Aims to provide not only a standardized format for error details, but also human-readable error messages (perfect for both internal and public APIs)
• Transforms both django.core.exceptions.ValidationError and rest_framework.errors.ValidationError to API errors, so you don't have to handle error raised by services/domain logic, clean(), etc.

Table of Contents

• Installation
• Usage
  • Exception Handler
  • Error structure overview
  • Example JSON Error Responses
  • Settings
    • CAMELIZE
    • EXTRA_HANDLERS
    • FIELDS_SEPARATOR
• Integration with drf-spectacular
• Support
• Contributing
  • Testing

Installation

Install using the command line:

pip install drf-simple-api-errors

Usage

Exception Handler

Add EXCEPTION_HANDLER in your REST_FRAMEWORK settings of your Django project settings file:

REST_FRAMEWORK = {
    # Your other settings...
    "EXCEPTION_HANDLER": "drf_simple_api_errors.exception_handler",
}

Error structure overview

API error messages will include the following keys:

• "title" (str): A brief summary that describes the problem type.
• "detail" (list[str] | None): A list of specific explanations related to the problem, if any.
• "invalid_params" (list[dict] | None): A list of dict containing details about parameters that were invalid or malformed in the request, if any. Each dict within this list provides:
  • "name" (str): The name of the parameter that was found to be invalid.
  • "reasons" (list[str]): A list of strings describing the specific reasons why the parameter was considered invalid or malformed.

{
  "title": "Error message.",
  "detail": ["error"],
  "invalid_params": [
    {
      "name": "field_name",
      "reason": ["error"]
    }
  ]
}

Example JSON Error Responses

Field validation errors

{
  "title": "Error message.",
  "detail": null,
  "invalid_params": [
    {
      "name": "field_name",
      "reason": ["error"]
    }
  ]
}

Non-fields validation errors

{
  "title": "Error message.",
  "detail": ["error"],
  "invalid_params": null
}

Other bad requests with no detail

{
  "title": "Error message.",
  "detail": null,
  "invalid_params": null
}

Settings

Default settings:

DRF_SIMPLE_API_ERRORS = {
    "CAMELIZE": False,
    "EXTRA_HANDLERS": [],
    "FIELDS_SEPARATOR": ".",
}

• CAMELIZE

Camel case support for Django Rest Framework exceptions JSON error responses.

If CAMELIZE is set to True:

{
  "title": "Error message.",
  "detail": null,
  "invalidParams": [
    {
      "name": "fieldName",
      "reason": ["error"]
    }
  ]
}

• EXTRA_HANDLERS

Support for exceptions that differ from the standard structure of the Django Rest Framework.

For example, if you need to customize how a specific exception is handled or want to format an existing exception differently, you can create your own handler.

To customize error handling for your project, simply create a new file (for example, extra_handlers.py) and define your own handler functions. This approach lets you tailor error responses to fit your specific needs.

Then add it to the EXTRA_HANDLERS list in this package settings:

DRF_SIMPLE_API_ERRORS = {
    "EXTRA_HANDLERS": [
        "path.to.my.extra_handlers.custom_handler",
        # ...
    ]
}

For reference, this library uses the same pattern for its own extra handlers here.

• FIELDS_SEPARATOR

Support for nested dicts containing multiple fields to be flattened.

If FIELDS_SEPARATOR is set to .:

{
    "field1": {
        "field2": "value"
    }
}

Will result in:

{
    "field1.field2": "value"
}

Integration with drf-spectacular

This library provides a drf-spectacular postprocessing hook that adds standardized error response schemas to your OpenAPI documentation.

Install with drf-spectacular support:

pip install drf-simple-api-errors[openapi]

Then add the postprocessing hook to your SPECTACULAR_SETTINGS:

SPECTACULAR_SETTINGS = {
    # Your other settings...
    "POSTPROCESSING_HOOKS": [
        # Only if you use djangorestframework-camel-case
        "drf_spectacular.contrib.djangorestframework_camel_case.camelize_serializer_fields",
        # Always include the hooks below
        "drf_spectacular.hooks.postprocess_schema_enums",
        "drf_simple_api_errors.integrations.spectacular.postprocess_schema_inject_errors",
    ],
}

The hook:

• Defines reusable APIError and InvalidParam schema components
• Adds error responses (400, 401, 403, 404, 500) to all API operations
• Respects the CAMELIZE setting for property names. When your API uses djangorestframework-camel-case, also include camelize_serializer_fields in POSTPROCESSING_HOOKS (as shown above) so request/response bodies and the injected error schemas stay consistently camel-cased.
• Does not overwrite error responses you have explicitly defined via @extend_schema

Place postprocess_schema_inject_errors last in POSTPROCESSING_HOOKS so any prior hooks have already shaped the operations before responses are injected.

By default, the hook injects responses for status codes 400, 401, 403, 404, and 500 on every operation. If some of those codes only apply to specific endpoints (e.g. 400 and 404), restrict the dict to codes that apply universally and declare the rest per-operation via @extend_schema:

DRF_SIMPLE_API_ERRORS = {
    # Your other settings...

    # Only inject universally applicable error responses (e.g. 401, 403, 500)
    "SPECTACULAR_ERROR_STATUS_CODES": {
        "401": "Unauthorized",
        "403": "Forbidden",
        "500": "Server error",
    },
}

N.B. If SPECTACULAR_ERROR_STATUS_CODES is set to an empty dict, only the APIError and InvalidParam schema components are injected — no error responses are attached to operations.

Support

Please open an issue.

Contributing

Please use the Github Flow. In a nutshell, create a branch, commit your code, and open a pull request.

Testing

All the necessary commands are included in the Makefile.

We are using tox and poetry to run tests in every supported Python version.

Run test during development with the commands below:

make install  # only if necessary
make test

Finally, run tox to ensure the changes work for every supported python version:

pip install tox  # only if necessary
tox -v