duck.contrib.responses.errors

Pre-built error response factories for common HTTP error status codes.

Thin wrappers around make_response that map each HTTP error class to a named function, providing a convenient one-call API for returning themed error pages from views and middleware.

Module Contents

Functions

async_bad_gateway	Asynchronously builds a 502 Bad Gateway response.
async_bad_request	Asynchronously builds the appropriate 4xx Bad Request response for a malformed request.
async_method_not_allowed	Asynchronously builds a 405 Method Not Allowed response.
async_not_found	Asynchronously builds a 404 Not Found response.
async_server_error	Asynchronously builds a 500 Internal Server Error response for an unhandled exception.
async_timeout_error	Asynchronously builds a 408 Request Timeout response.
bad_gateway	Builds a 502 Bad Gateway response.
bad_request	Builds the appropriate 4xx Bad Request response for a malformed request.
build_route_list	Converts the RouteRegistry url_map into a list of template-friendly dicts.
method_not_allowed	Builds a 405 Method Not Allowed response.
not_found	Builds a 404 Not Found response.
server_error	Builds a 500 Internal Server Error response for an unhandled exception.
timeout_error	Builds a 408 Request Timeout response.

API

async duck.contrib.responses.errors.async_bad_gateway(exception: Optional[Exception] = None, request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpResponse

Asynchronously builds a 502 Bad Gateway response.

Typically raised when an upstream server or proxied service returns an invalid or no response. In debug mode the exception detail is included in the response body.

Parameters:

• exception – The exception that triggered the bad gateway condition, if available.

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE in request metadata and to enrich the debug body.

Returns:

A themed HttpBadGatewayResponse.

async duck.contrib.responses.errors.async_bad_request(exception: Exception, request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpResponse

Asynchronously builds the appropriate 4xx Bad Request response for a malformed request.

Inspects the exception type to select the most specific response class and body message. Handles three distinct cases:

• RequestSyntaxError ➝ 400 Bad Request Syntax

• RequestUnsupportedVersionError ➝ 505 HTTP Version Not Supported

• HTTPS-over-HTTP detection ➝ 400 with a protocol mismatch hint

• All other cases ➝ generic 400 Bad Request

In debug mode the exception reference is appended to the body. In production the body is suppressed entirely.

Parameters:

• exception – The exception describing the malformed request.

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE with a context-specific message for each error type.

Returns:

A themed HttpResponse with the appropriate 4xx status code.

async duck.contrib.responses.errors.async_method_not_allowed(request: Optional[duck.http.request.HttpRequest] = None, route_info: Optional[Dict[str, Any]] = None) → duck.http.response.HttpResponse

Asynchronously builds a 405 Method Not Allowed response.

In debug mode the allowed methods for the matched route are surfaced in the response body so developers can identify the correct verb quickly.

Parameters:

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE with the disallowed method.

• route_info – The matched route’s metadata as returned by RouteRegistry. When provided, the allowed methods list is extracted and shown.

Returns:

A themed HttpMethodNotAllowedResponse.

async duck.contrib.responses.errors.async_not_found(request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpResponse

Asynchronously builds a 404 Not Found response.

In debug mode the response lists all routes currently registered in the RouteRegistry so developers can diagnose mismatched or missing URL patterns. A Django-specific hint is appended when USE_DJANGO=True to surface the DJANGO_SIDE_URLS option.

Parameters:

request – The active HTTP request. Used to annotate DEBUG_MESSAGE and to include the requested path in the debug body.

Returns:

A themed HttpNotFoundResponse.

async duck.contrib.responses.errors.async_server_error(exception: Exception, request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpResponse

Asynchronously builds a 500 Internal Server Error response for an unhandled exception.

In debug mode the full exception traceback and request metadata are rendered into the response body. In production the body is suppressed to avoid leaking internal details.

Parameters:

• exception – The unhandled exception that triggered this error.

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE in request metadata and to enrich the debug body.

Returns:

A themed HttpServerErrorResponse.

async duck.contrib.responses.errors.async_timeout_error(timeout: Optional[Union[int, float]] = None) → duck.http.response.HttpRequestTimeoutResponse

Asynchronously builds a 408 Request Timeout response.

In debug mode the response body includes the configured timeout value so developers can identify slow or stalled client connections quickly.

Parameters:

timeout – The timeout threshold in seconds that was exceeded. When provided, the value is surfaced in the debug body.

Returns:

A themed HttpRequestTimeoutResponse.

duck.contrib.responses.errors.bad_gateway(exception: Optional[Exception] = None, request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpResponse

Builds a 502 Bad Gateway response.

Typically raised when an upstream server or proxied service returns an invalid or no response. In debug mode the exception detail is included in the response body.

Parameters:

• exception – The exception that triggered the bad gateway condition, if available.

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE in request metadata and to enrich the debug body.

Returns:

A themed HttpBadGatewayResponse.

duck.contrib.responses.errors.bad_request(exception: Exception, request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpResponse

Builds the appropriate 4xx Bad Request response for a malformed request.

Inspects the exception type to select the most specific response class and body message. Handles three distinct cases:

• RequestSyntaxError ➝ 400 Bad Request Syntax

• RequestUnsupportedVersionError ➝ 505 HTTP Version Not Supported

• HTTPS-over-HTTP detection ➝ 400 with a protocol mismatch hint

• All other cases ➝ generic 400 Bad Request

In debug mode the exception reference is appended to the body. In production the body is suppressed entirely.

Parameters:

• exception – The exception describing the malformed request.

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE with a context-specific message for each error type.

Returns:

A themed HttpResponse with the appropriate 4xx status code.

duck.contrib.responses.errors.build_route_list() → list[dict]

Converts the RouteRegistry url_map into a list of template-friendly dicts.

Each entry exposes the URL pattern, its registered name, and any HTTP methods declared on the route handler. The pattern is HTML-escaped so the template can render angle-bracket parameters safely.

Returns:

pattern (str), name (str), methods (list[str]).

Return type:

A list of dicts with keys

duck.contrib.responses.errors.method_not_allowed(request: Optional[duck.http.request.HttpRequest] = None, route_info: Optional[Dict[str, Any]] = None) → duck.http.response.HttpResponse

Builds a 405 Method Not Allowed response.

In debug mode the allowed methods for the matched route are surfaced in the response body so developers can identify the correct verb quickly.

Parameters:

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE with the disallowed method.

• route_info – The matched route’s metadata as returned by RouteRegistry. When provided, the allowed methods list is extracted and shown.

Returns:

A themed HttpMethodNotAllowedResponse.

duck.contrib.responses.errors.not_found(request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpNotFoundResponse

Builds a 404 Not Found response.

In debug mode the response renders the full route registry so developers can quickly spot mismatched or missing URL patterns. A Django-specific hint is included when USE_DJANGO=True to surface the DJANGO_SIDE_URLS option.

Parameters:

request – The active HTTP request. Used to annotate DEBUG_MESSAGE and to supply the requested path to the template.

Returns:

A themed HttpNotFoundResponse rendered from 404.html.

duck.contrib.responses.errors.server_error(exception: Exception, request: Optional[duck.http.request.HttpRequest] = None) → duck.http.response.HttpResponse

Builds a 500 Internal Server Error response for an unhandled exception.

In debug mode the full exception traceback and request metadata are rendered into the response body. In production the body is suppressed to avoid leaking internal details.

Parameters:

• exception – The unhandled exception that triggered this error.

• request – The active HTTP request. Used to annotate DEBUG_MESSAGE in request metadata and to enrich the debug body.

Returns:

A themed HttpServerErrorResponse.

duck.contrib.responses.errors.timeout_error(timeout: Optional[Union[int, float]] = None) → duck.http.response.HttpRequestTimeoutResponse

Builds a 408 Request Timeout response.

In debug mode the response body includes the configured timeout value so developers can identify slow or stalled client connections quickly.

Parameters:

timeout – The timeout threshold in seconds that was exceeded. When provided, the value is surfaced in the debug body.

Returns:

A themed HttpRequestTimeoutResponse.