Errors

Errors#

ADR 0029 standardized error responses: the exception handler and its envelope formatters, the Conflict exception, the error-type URI catalog with its register_error_type extension helper, and the ErrorResponseSerializer that documents the envelope in OpenAPI schemas. The handler delegates to a base handler resolved from the EDX_DRF_EXTENSIONS['STANDARDIZED_ERROR_BASE_HANDLER'] setting, so services keep their own error-monitoring behavior.

exception Conflict(detail=None, code=None)#

HTTP 409 Conflict — ADR 0029.

ERROR_TYPE_BASE_URI = 'https://docs.openedx.org/errors/'#

Base URI under which every ADR 0029 error-type slug is published.

class ErrorResponseSerializer(*args, **kwargs)#

Plain-DRF serializer describing the ADR 0029 error envelope.

Intended for OpenAPI response declarations so error responses are documented with their real shape, e.g. with drf-spectacular:

@extend_schema(responses={
    200: MyResourceSerializer,
    404: ErrorResponseSerializer,
})

It is a documentation serializer: nothing deserializes through it, so it implements no create/update.

INTERNAL_ERROR_SLUG = 'internal'#

Slug and title used when an exception matches nothing in the catalog.

build_error_envelope(exc, response, request=None)#

Build the ADR 0029 error envelope for exc.

Parameters:

  • exc (Exception) – the exception the view raised.

  • response (rest_framework.response.Response) – the response produced by the base exception handler; supplies the status code and the raw error data that detail is flattened from.

  • request – the request being handled, if available; supplies instance.

Returns:

the envelope, ready to be assigned to response.data.

Return type:

dict

classify_error(exc)#

Return the (slug, title) catalog entry for the exception exc.

Falls back to (INTERNAL_ERROR_SLUG, INTERNAL_ERROR_TITLE) when the exception matches neither a registered nor a built-in catalog entry.

error_type_uri(slug)#

Return the full ADR 0029 error-type URI for slug (e.g. "authn").

flatten_detail(data)#

Extract a single string detail message from a DRF response data payload.

normalize_validation_errors(detail)#

Convert DRF validation error detail into a consistent per-field dict.

register_error_type(exception_class, slug, title)#

Extend the ADR 0029 error-type catalog with a custom exception class.

After registration, any raised instance of exception_class (or a subclass) is enveloped with type error_type_uri(slug) and title title. Registrations are consulted most-recent-first and take precedence over the built-in catalog, so registering a subclass of a cataloged exception specializes it.

Parameters:

  • exception_class (type) – the exception class to classify.

  • slug (str) – the error-type slug, appended to ERROR_TYPE_BASE_URI.

  • title (str) – the human-readable envelope title.

standardized_error_exception_handler(exc, context)#

ADR 0029 — DRF exception handler returning the standardized error envelope.

Delegates to the base handler (see _base_exception_handler()) and reformats its response via build_error_envelope(). When the base handler declines to handle the exception (returns None, DRF’s behavior for non-APIException errors), a generic internal 500 envelope is returned instead of re-raising.

Contents