Error handling

django-modern-rest has 3 layers where errors might be handled. It provides flexible error handling logic on Endpoint, Controller, and global levels.

All error handling functions always accept 3 arguments:

1. Endpoint where error happened

2. Controller where error happened

3. Exception that happened

Here’s how it works:

1. We first try to call error_handler that was passed into the endpoint definition via modify() or validate()

2. If it returns django.http.HttpResponse, return it to the user

3. If it raises, call handle_error() for sync controllers and handle_async_error() for async controllers

4. If controller’s handler returns HttpResponse, return it to the user

5. If it raises, call configured global error handler, by default it is global_error_handler() (it is always sync)

Warning

There are two things to keep in mind:

1. Async endpoints will require async error_handler parameter, Sync endpoints will require sync error_handler parameter. This is validated on endpoint creation

2. We don’t allow to define sync handle_error handlers for async controllers. We also don’t allow async handle_async_error handlers for sync controllers.

Note

APIError does not follow any of these rules and has a default handler, which will convert an instance of APIError to HttpResponse via to_error() call.

You don’t need to catch APIError in any way, unless you know what you are doing.

Customizing endpoint error handler

Let’s pass custom error handling to a single endpoint:

views.py

Show imports... 11 lines hidden

[source]

from http import HTTPStatus

import pydantic
from django.http import HttpResponse

from dmr import Body, Controller, modify
from dmr.endpoint import Endpoint
from dmr.plugins.pydantic import PydanticSerializer
from dmr.serializer import BaseSerializer


class TwoNumbers(pydantic.BaseModel):
    left: int
    right: int


def division_error(  # <- we define an error handler
    endpoint: Endpoint,
    controller: Controller[BaseSerializer],
    exc: Exception,
) -> HttpResponse:
    if isinstance(exc, ZeroDivisionError):
        # This response's schema was automatically added by `Body`:
        return controller.to_error(
            controller.format_error(str(exc)),
            status_code=HTTPStatus.BAD_REQUEST,
        )
    # Reraise unfamiliar errors to let someone
    # else to handle them further.
    raise exc from None


class MathController(Controller[PydanticSerializer]):
    @modify(error_handler=division_error)  # <- and we pass the handler
    def patch(
        self,
        parsed_body: Body[TwoNumbers],
    ) -> float:  # <- has custom error handling
        return parsed_body.left / parsed_body.right

    def post(
        self,
        parsed_body: Body[TwoNumbers],
    ) -> float:  # <- has only default error handling
        return parsed_body.left / parsed_body.right

Run result

$ curl http://127.0.0.1:8000/api/math/ -D - -X PATCH -d '{"left": 1, "right": 0}' -H 'Content-Type: application/json'
HTTP/1.1 400 Bad Request
date: Tue, 26 May 2026 19:08:17 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 39
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"division by zero"}]}

$ curl http://127.0.0.1:8000/api/math/ -D - -X POST -d '{"left": 1, "right": 0}' -H 'Content-Type: application/json'
HTTP/1.1 500 Internal Server Error
date: Tue, 26 May 2026 19:08:18 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 68
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Internal server error","type":"internal_error"}]}

In this example we add error handling defined as division_error to patch endpoint (which serves as a division operation), while keeping post endpoint (which serves as a multiply operation) without a custom error handler. Because ZeroDivisionError can’t happen in post.

Per-endpoint’s error handling has a priority over per-controller and global handlers.

You can also define endpoint error handlers as controller methods and pass them wrapped with wrap_handler() as handlers. Like so:

views.py

Show imports... 12 lines hidden

[source]

from http import HTTPStatus

import pydantic
from django.http import HttpResponse

from dmr import Body, Controller, modify
from dmr.endpoint import Endpoint
from dmr.errors import wrap_handler
from dmr.plugins.pydantic import PydanticSerializer
from dmr.serializer import BaseSerializer


class TwoNumbers(pydantic.BaseModel):
    left: int
    right: int


class MathController(Controller[PydanticSerializer]):
    def division_error(  # <- we define an error handler
        self,
        endpoint: Endpoint,
        controller: Controller[BaseSerializer],
        exc: Exception,
    ) -> HttpResponse:
        if isinstance(exc, ZeroDivisionError):
            # This response's schema was automatically added by `Body`:
            return controller.to_error(
                controller.format_error(str(exc)),
                status_code=HTTPStatus.BAD_REQUEST,
            )
        # Reraise unfamiliar errors to let someone
        # else to handle them further.
        raise exc from None

    @modify(
        error_handler=wrap_handler(  # <- and we pass the handler
            division_error,
        ),
    )
    def patch(
        self,
        parsed_body: Body[TwoNumbers],
    ) -> float:  # <- has custom error handling
        return parsed_body.left / parsed_body.right

    def post(
        self,
        parsed_body: Body[TwoNumbers],
    ) -> float:  # <- has only default error handling
        return parsed_body.left * parsed_body.right

Run result

$ curl http://127.0.0.1:8000/api/math/ -D - -X PATCH -d '{"left": 1, "right": 0}' -H 'Content-Type: application/json'
HTTP/1.1 400 Bad Request
date: Tue, 26 May 2026 19:08:18 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 39
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"division by zero"}]}

Customizing controller error handler

Let’s create custom error handling for the whole controller:

views.py

Show imports... 11 lines hidden

[source]

from http import HTTPStatus

import zapros
from django.http import HttpResponse
from typing_extensions import override

from dmr import Controller, ResponseSpec
from dmr.endpoint import Endpoint
from dmr.plugins.pydantic import PydanticSerializer


class ProxyController(Controller[PydanticSerializer]):
    responses = (
        # Custom schema that we can return when `HTTPError` happens:
        ResponseSpec(str, status_code=HTTPStatus.FAILED_DEPENDENCY),
    )

    async def get(self) -> None:
        async with self._client() as client:
            # Simulate some real work:
            await client.get('https://example.com')

    async def post(self) -> None:
        async with self._client() as client:
            # Simulate some real work:
            await client.post('https://example.com', json={})

    @override
    async def handle_async_error(
        self,
        endpoint: Endpoint,
        controller: Controller[PydanticSerializer],
        exc: Exception,
    ) -> HttpResponse:
        # Will handle errors in all endpoints.
        if isinstance(exc, zapros.ZaprosError):
            return self.to_error(
                'Request to example.com failed',
                status_code=HTTPStatus.FAILED_DEPENDENCY,
            )
        # Handle errors from super:
        return await super().handle_async_error(
            endpoint,
            controller,
            exc,
        )

    def _client(self) -> zapros.AsyncClient:
        return zapros.AsyncClient()

In this example we are using zapros HTTP client to proxy an HTTP GET and POST requests to some other API service. If we fail to send a request and raise a specific HTTP client error, we return an error with 424 error code.

Going further

Now you can understand how you can create:

• Endpoints with custom error handlers

• Controllers with custom error handlers

• ResponseSpec objects for new error response schemas

You can dive even deeper and:

• Subclass Controller and provide default error handling for this specific subclass

• Redefine endpoint_cls and change how one specific endpoint behaves on a deep level, see handle_error() and handle_async_error()

Error handling diagram

The same error handling logic can be represented as a diagram:

        ---
config:
  theme: forest

---
graph TB
    Start[Request] --> Error{Error?};
    Error -->|Yes| Endpoint[Endpoint-level handler];
    Endpoint --> EndpointHandler{Raises or returns response?};
    EndpointHandler -->|response| Failure[Error response];
    EndpointHandler -->|raises| Controller[Controller-level handler];
    Controller --> ControllerHandler{Raises or returns response?};
    ControllerHandler -->|response| Failure[Error response];
    ControllerHandler -->|raises| Global[Global handler];
    Global --> GlobalHandler{Raises or returns response?};
    GlobalHandler -->|response| Failure[Error response];
    GlobalHandler -->|raises| Reraises[Reraises error];
    Error ---->|No| Success[Successful response];
    

Error handling logic

Note

If Handling 500 errors is configured, it will catch all unhandled errors in the provided scope and return 500 errors with the correct payload.

Customizing error messages

All error messages, including pre-defined ones, can be easily customized on a per-controller basis.

To do so, you would need to change:

1. error_model attribute for all controllers that will be using this error message schema

2. format_error() method to provide custom runtime error formatting

views.py

Show imports... 9 lines hidden

[source]

from http import HTTPStatus

from typing_extensions import TypedDict, override

from dmr import APIError, Body, Controller, ResponseSpec, modify
from dmr.errors import ErrorType, format_error
from dmr.plugins.pydantic import PydanticSerializer


class CustomErrorDetail(TypedDict):
    message: str


class CustomErrorModel(TypedDict):
    errors: list[CustomErrorDetail]


class ApiController(Controller[PydanticSerializer]):
    error_model = CustomErrorModel

    @override
    def format_error(
        self,
        error: str | Exception,
        *,
        loc: str | list[str | int] | None = None,
        error_type: str | ErrorType | None = None,
    ) -> CustomErrorModel:
        default = format_error(
            error,
            loc=loc,
            error_type=error_type,
        )
        return {
            'errors': [
                {'message': detail['msg']} for detail in default['detail']
            ],
        }

    @modify(
        extra_responses=[
            ResponseSpec(
                return_type=CustomErrorModel,
                status_code=HTTPStatus.PAYMENT_REQUIRED,
            ),
        ],
    )
    def post(self, parsed_body: Body[dict[str, str]]) -> str:
        raise APIError(
            self.format_error('test msg'),
            status_code=HTTPStatus.PAYMENT_REQUIRED,
        )

Run result

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '{}' -H 'Content-Type: application/json'
{"errors":[{"message":"test msg"}]}

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '[]' -H 'Content-Type: application/json'
{"errors":[{"message":"Input should be a valid dictionary"}]}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "CustomErrorDetail": {
        "properties": {
          "message": {
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "title": "CustomErrorDetail",
        "type": "object"
      },
      "CustomErrorModel": {
        "properties": {
          "errors": {
            "items": {
              "$ref": "#/components/schemas/CustomErrorDetail"
            },
            "title": "Errors",
            "type": "array"
          }
        },
        "required": [
          "errors"
        ],
        "title": "CustomErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/apicontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postApicontrollerApiApicontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomErrorModel"
                }
              }
            },
            "description": "Payment Required"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

This will also change the OpenAPI schema for the affected controller.

See ErrorModel for the default error model schema. And format_error() for the default error formatting.

See content negotiation docs about how to use different error models for different content types.

Customizing error headers and cookies

Let’s say you want to customize how all errors responses behave and add a header, for example, X-Error-Id from your error tracking system.

How this can be done?

views.py

Show imports... 14 lines hidden

[source]

from collections.abc import Mapping
from http import HTTPStatus
from typing import Annotated, Any

from django.http import HttpResponse
from typing_extensions import override

from dmr import Body, Controller, HeaderSpec, NewCookie
from dmr.errors import ErrorModel
from dmr.metadata import ResponseSpecMetadata
from dmr.plugins.pydantic import PydanticSerializer
from dmr.renderers import Renderer


class ApiController(Controller[PydanticSerializer]):
    error_model = Annotated[
        ErrorModel,
        ResponseSpecMetadata(headers={'X-Error-Id': HeaderSpec()}),
    ]

    def post(self, parsed_body: Body[dict[str, str]]) -> dict[str, str]:
        return parsed_body

    @override
    def to_error(
        self,
        raw_data: Any,
        *,
        status_code: HTTPStatus,
        headers: Mapping[str, str] | None = None,
        cookies: Mapping[str, NewCookie] | None = None,
        renderer: Renderer | None = None,
    ) -> HttpResponse:
        headers = dict(headers or {})
        headers.setdefault('X-Error-Id', 'Error-Id from your provider')

        return super().to_error(
            raw_data,
            status_code=status_code,
            headers=headers,
            cookies=cookies,
            renderer=renderer,
        )

Run result

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '{"key": "value"}' -H 'Content-Type: application/json'
{"key":"value"}

$ curl http://127.0.0.1:8000/api/example/ -D - -X POST -d '[]' -H 'Content-Type: application/json'
HTTP/1.1 400 Bad Request
date: Tue, 26 May 2026 19:08:19 GMT
server: uvicorn
X-Error-Id: Error-Id from your provider
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 100
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Input should be a valid dictionary","loc":["parsed_body"],"type":"value_error"}]}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/apicontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postApicontrollerApiApicontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed",
            "headers": {
              "X-Error-Id": {
                "required": true,
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied",
            "headers": {
              "X-Error-Id": {
                "required": true,
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema",
            "headers": {
              "X-Error-Id": {
                "required": true,
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}

To attach response headers or cookies to the error model we use ResponseSpecMetadata inside typing.Annotated type.

We also have to redefine to_error() to add missing X-Error-Id headers for your error responses.

You can do the same for all responses, not just failing ones. For this, override to_response().

This can also be used to attach RateLimit headers and other Throttling information.

Problem Details

See also

RFC: https://datatracker.ietf.org/doc/html/rfc9457

django-modern-rest supports customizing of all error message inside the framework, including builtin ones.

ProblemDetailsError is a great example of how it can be done.

It is a regular subclass of APIError, which does not have any special handling inside our framework. This is done on purpose, so we can be sure that users also can to customize their exceptions any way they need.

We support two main use-cases for Problem Details.

Always raising Problem Details

To always use ProblemDetailsError inside your controller you would need to:

1. Define error_model attribute as ProblemDetailsModel

2. Raise an exception itself, pass all the required fields

3. Convert other message to the Problem Details format using format_error() method

views.py

Show imports... 12 lines hidden

[source]

from http import HTTPStatus
from typing import Any

import pydantic
from typing_extensions import override

from dmr import Controller, Query, ResponseSpec
from dmr.errors import ErrorType
from dmr.plugins.pydantic import PydanticSerializer
from dmr.problem_details import ProblemDetailsError, ProblemDetailsModel


class _QueryModel(pydantic.BaseModel):
    number: int = 0


class ProblemDetailsController(Controller[PydanticSerializer]):
    error_model = ProblemDetailsModel

    responses = (
        ResponseSpec(error_model, status_code=HTTPStatus.PAYMENT_REQUIRED),
    )

    async def get(self, parsed_query: Query[_QueryModel]) -> str:
        raise ProblemDetailsError(
            (
                f'Your current balance is {parsed_query.number}, '
                'but the price is 15'
            ),
            status_code=HTTPStatus.PAYMENT_REQUIRED,
            type='https://example.com/probs/out-of-credit',
            title='Not enough funds',
            instance='/account/users/1/',
            extra={'balance': parsed_query.number, 'price': 15},
        )

    @override
    def format_error(
        self,
        error: str | Exception,
        *,
        loc: str | list[str | int] | None = None,
        error_type: str | ErrorType | None = None,
    ) -> Any:
        return ProblemDetailsError.format_error(
            error,
            loc=loc,
            error_type=error_type,
            title='From format_error',
        )

Run result

$ curl http://127.0.0.1:8000/api/balance/ -X GET
{"detail":"Your current balance is 0, but the price is 15","status":402,"type":"https://example.com/probs/out-of-credit","title":"Not enough funds","instance":"/account/users/1/","balance":0,"price":15}

$ curl 'http://127.0.0.1:8000/api/balance/?number=a' -X GET
{"detail":"Input should be a valid integer, unable to parse string as an integer","status":400,"type":"value_error","title":"From format_error"}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ProblemDetailsModel": {
        "description": "Error payload model for Problem Details.\n\nSee https://datatracker.ietf.org/doc/html/rfc9457\nfor the detailed description of each field.",
        "properties": {
          "detail": {
            "title": "Detail",
            "type": "string"
          },
          "instance": {
            "title": "Instance",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "integer"
          },
          "title": {
            "title": "Title",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "title": "ProblemDetailsModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/problemdetailscontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getProblemdetailscontrollerApiProblemdetailscontroller",
        "parameters": [
          {
            "deprecated": false,
            "in": "query",
            "name": "number",
            "schema": {
              "default": 0,
              "title": "Number",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsModel"
                }
              }
            },
            "description": "Payment Required"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Conditionally raising Problem Details

Another way is to negotiate the error response format. How does it work?

1. When user sends a request with Accept header with application/problem+json content type, we will return Problem Details errors

2. When application/json or any other content type is sent, we return regular ErrorModel error payloads

To do so, you would need a slightly more difficult setup:

1. Define error_model attribute as the result of error_model() method call. It will add conditional schema types to your error responses

2. Define several Renderer types, including the one which will handle application/problem+json

3. Raise a conditional exception: use conditional_error() to only raise Problem Details when the correct accepted type is passed

4. Convert other message to the Problem Details format using format_error() method when the correct accepted type is passed

views.py

Show imports... 13 lines hidden

[source]

from http import HTTPStatus
from typing import Any

from typing_extensions import override

from dmr import Controller, ResponseSpec
from dmr.errors import ErrorModel, ErrorType
from dmr.negotiation import ContentType, accepts
from dmr.plugins.pydantic import PydanticSerializer
from dmr.problem_details import ProblemDetailsError
from dmr.renderers import JsonRenderer


class ProblemDetailsController(Controller[PydanticSerializer]):
    error_model = ProblemDetailsError.error_model({
        ContentType.json: ErrorModel,
    })

    renderers = (
        JsonRenderer(ContentType.json),
        JsonRenderer(ContentType.json_problem_details),
    )

    responses = (
        ResponseSpec(error_model, status_code=HTTPStatus.PAYMENT_REQUIRED),
    )

    async def get(self) -> str:
        raise ProblemDetailsError.conditional_error(
            'Your current balance is 0, but the price is 15',
            status_code=HTTPStatus.PAYMENT_REQUIRED,
            type='https://example.com/probs/out-of-credit',
            title='Not enough funds',
            instance='/account/users/1/',
            extra={'balance': 0, 'price': 15},
            controller=self,
        )

    @override
    def format_error(
        self,
        error: str | Exception,
        *,
        loc: str | list[str | int] | None = None,
        error_type: str | ErrorType | None = None,
    ) -> Any:
        if accepts(self.request, ContentType.json_problem_details):
            return ProblemDetailsError.format_error(
                error,
                loc=loc,
                error_type=error_type,
                title='From format_error',
            )
        return super().format_error(error, loc=loc, error_type=error_type)

Run result

$ curl http://127.0.0.1:8000/api/balance/ -X GET
{"detail":[{"msg":"Your current balance is 0, but the price is 15","type":"https://example.com/probs/out-of-credit"}]}

$ curl http://127.0.0.1:8000/api/balance/ -X GET -H 'Accept: application/problem+json'
{"detail":"Your current balance is 0, but the price is 15","status":402,"type":"https://example.com/probs/out-of-credit","title":"Not enough funds","instance":"/account/users/1/","balance":0,"price":15}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "ProblemDetailsModel": {
        "description": "Error payload model for Problem Details.\n\nSee https://datatracker.ietf.org/doc/html/rfc9457\nfor the detailed description of each field.",
        "properties": {
          "detail": {
            "title": "Detail",
            "type": "string"
          },
          "instance": {
            "title": "Instance",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "integer"
          },
          "title": {
            "title": "Title",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "title": "ProblemDetailsModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/problemdetailscontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getProblemdetailscontrollerApiProblemdetailscontroller",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "application/problem+json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "OK"
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsModel"
                }
              }
            },
            "description": "Payment Required"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetailsModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Tip

You can still make application/problem+json the default and when application/json (or any other type) is explicitly requested return the ErrorModel errors.

Handling validation errors from models

When creating models with, for example, pydantic.BaseModel, your validation can fail. This error will not be handled by design.

Why? Because catching all specific validation errors for a specific serializer that can happen in your application will do more harm than good.

This is the default behavior:

views.py

Show imports... 8 lines hidden

[source]

from typing import Literal

import pydantic

from dmr import Controller
from dmr.plugins.pydantic import PydanticSerializer


class Pong(pydantic.BaseModel):
    message: Literal['pong']


class PongController(Controller[PydanticSerializer]):
    def get(self) -> Pong:
        # This will trigger `pydantic.ValidationError`,
        # because `message` must be `'pong'`, not `'wrong'`:
        return Pong(message='wrong')

Run result

$ curl http://127.0.0.1:8000/api/ping/ -D - -X GET
HTTP/1.1 500 Internal Server Error
date: Tue, 26 May 2026 19:08:22 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 68
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Internal server error","type":"internal_error"}]}

If you want to catch this error in a specific place and attach a specific behavior, use an error handler at a proper level.

For example, here we would handle it on a controller level:

views.py

Show imports... 12 lines hidden

[source]

from http import HTTPStatus
from typing import Literal

import pydantic
from django.http import HttpResponse
from typing_extensions import override

from dmr import Controller, ResponseSpec
from dmr.endpoint import Endpoint
from dmr.plugins.pydantic import PydanticSerializer


class Pong(pydantic.BaseModel):
    message: Literal['pong']


class PongController(Controller[PydanticSerializer]):
    responses = (
        ResponseSpec(
            Controller.error_model,
            status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
        ),
    )

    def get(self) -> Pong:
        # This will trigger `pydantic.ValidationError`,
        # because `message` must be `'pong'`, not `'wrong'`:
        return Pong(message='wrong')

    @override
    def handle_error(
        self,
        endpoint: Endpoint,
        controller: Controller[PydanticSerializer],
        exc: Exception,
    ) -> HttpResponse:
        if isinstance(exc, pydantic.ValidationError):
            # Now, handle the error, but do not show what actually happened
            # to the outside world, it might contain sensitive data:
            return self.to_response(
                self.format_error('Validation error'),
                status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
            )
        return super().handle_error(endpoint, controller, exc)

Run result

$ curl http://127.0.0.1:8000/api/ping/ -D - -X GET
HTTP/1.1 500 Internal Server Error
date: Tue, 26 May 2026 19:08:22 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 39
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Validation error"}]}

Now, the error is handled: we modified its error text and status code. Remember not to dump all the error information out to users, since they might contain sensitive data.

See also

See Handling 500 errors if you want to change the 500 error rendering.

API Reference

dmr.errors.global_error_handler(endpoint: Endpoint, controller: Controller[BaseSerializer], exc: Exception) → HttpResponse

Global error handler for all cases.

It is the last item in the chain that we try:

1. Per endpoint configuration via handle_error() and handle_async_error() methods

2. Per controller handlers

3. This global handler, specified via the configuration

If some exception cannot be handled, it is just reraised.

Parameters:

• endpoint – Endpoint where error happened.

• controller – Controller instance that endpoint belongs to.

• exc – Exception instance that happened.

Returns:

HttpResponse with proper response for this error. Or raise exc back.

Here’s an example that will produce {'detail': [{'msg': 'inf', 'type': 'user_msg'}]} for any ZeroDivisionError in your application:

>>> from http import HTTPStatus
>>> from django.http import HttpResponse
>>> from dmr.controller import Controller
>>> from dmr.endpoint import Endpoint
>>> from dmr.errors import global_error_handler, ErrorType

>>> def custom_error_handler(
...     controller: Controller,
...     endpoint: Endpoint,
...     exc: Exception,
... ) -> HttpResponse:
...     if isinstance(exc, ZeroDivisionError):
...         return controller.to_error(
...             controller.format_error(
...                 'inf',
...                 error_type=ErrorType.user_msg,
...             ),
...             status_code=HTTPStatus.NOT_IMPLEMENTED,
...         )
...     # Call the original handler to handle default errors:
...     return global_error_handler(controller, endpoint, exc)

>>> # And then in your settings file:
>>> DMR_SETTINGS = {
...     # Object `custom_error_handler` will also work:
...     'global_error_handler': 'path.to.custom_error_handler',
... }

Warning

Make sure you always call original global_error_handler in the very end. Unless, you want to disable original error handling.

dmr.errors.wrap_handler(method: _MethodSyncHandler) → SyncErrorHandler

dmr.errors.wrap_handler(method: _MethodAsyncHandler) → AsyncErrorHandler

Utility function to wrap controller methods.

It is used to wrap an existing controller method and pass it as error_handler= argument to an endpoint.

final class dmr.errors.ErrorType(*values)

Collection of all possible error types that we use in DMR.

value_error

Raised when we can’t parse something.

internal_error

Raised when internal error happens.

not_allowed

Raised when using unsupported http method. 405 alias.

security

Raised when security related error happens.

ratelimit

Raised when ratelimit related error happens.

user_msg

Raised for custom errors from users.

not_found

Raised when we can’t find controller.

streaming

Happens when we stream events.

class dmr.errors.ErrorModel

Default error response schema.

Can be customized. See Customizing error messages for more details.

class dmr.errors.ErrorDetail

Base schema for error details description.

dmr.errors.format_error(error: str | Exception, *, loc: str | list[str | int] | None = None, error_type: str | ErrorType | None = None) → ErrorModel

Convert error to the common format.

Default implementation.

Parameters:

• error – A serialization exception like a validation error.

• loc – Location where this error happened. Like "headers", or "field_name", or ["parsed_headers", "header_name"].

• error_type – Optional type of the error for extra metadata.

Returns:

Simple python object - exception converted to a common format.

Problem Details API

class dmr.problem_details.ProblemDetailsError(detail: str, *, status_code: HTTPStatus, type: str | None = None, title: str | None = None, instance: str | None = None, extra: Mapping[str, Any] | None = None, headers: Mapping[str, str] | None = None, cookies: Mapping[str, NewCookie] | None = None, show_status: bool = True, show_detail: bool = True)

Bases: APIError[ProblemDetailsModel]

Problem Details exception.

It is a subclass of dmr.response.APIError, so you can raise it anywhere in the REST part of your app.

There are two major use-cases that we support for this class:

1. Direct usage: you raise an error and get what you raise, no changes

2. Conditional usage: you call conditional_error method and if the client accepts application/problem+json, we will return the proper Problem Details description. But, if it is not requested directly, we will return our regular dmr.errors.ErrorModel

Both use-cases are independent. You can decide what to use per controller.

classmethod conditional_error(detail: str, *, status_code: HTTPStatus, controller: Controller[BaseSerializer], type: str | None = None, title: str | None = None, instance: str | None = None, extra: Mapping[str, Any] | None = None, headers: Mapping[str, str] | None = None, cookies: Mapping[str, NewCookie] | None = None, show_status: bool = True, show_detail: bool = True) → APIError[Any]

Create conditional error.

If request accepts application/problem+json then return a Problem Details exception. If not, return regular dmr.response.APIError instance.

Otherwise, returns regular error from controller using its format_error() method for formatting.

classmethod error_model(existing_errors: Mapping[str, Any], content_type: str | None = None) → Any

Builds an error model for conditional responses.

Only use this method when you use conditional_error. If you are using regular exceptions, use ProblemDetailsModel directly.

classmethod format_error(error: str | Exception, *, loc: str | list[str | int] | None = None, error_type: str | ErrorType | None = None, status_code: HTTPStatus | None = None, title: str | None = None, instance: str | None = None, extra: Mapping[str, Any] | None = None) → ErrorModel | ProblemDetailsModel

Format other errors to be in format of Problem Details.

class dmr.problem_details.ProblemDetailsModel

Error payload model for Problem Details.

See https://datatracker.ietf.org/doc/html/rfc9457 for the detailed description of each field.