Responses

Execution Workflow

• Start with the simplest return form that matches the contract: plain typed data, Response[T] , or a specialized response container.

• Set status code, media type, headers, and cookies explicitly when defaults are not enough.

• Choose specialized response types for redirects, files, streams, SSE, templates, or third-party ASGI responses.

• Apply response-class layering only when serialization or envelope behavior should be shared across many handlers.

• Verify OpenAPI accuracy for typed responses, documentation-only headers/cookies, empty-body statuses, and specialized response containers.

Core Rules

• Prefer plain typed returns for standard JSON responses.

• Use Response[T] when you need runtime control over headers, cookies, background tasks, or status code.

• Keep generic arguments on response classes precise so schema generation stays accurate.

• Document runtime headers and cookies when clients depend on them, especially if values are set dynamically.

• Treat 204 , 304 , and other no-body responses as None -returning contracts.

• Keep success envelopes consistent with exception-handling envelopes where the API uses a shared contract.

• Use specialized response containers instead of reimplementing file, redirect, stream, or SSE behavior manually.

• Keep layered response_class , response_headers , and response_cookies overrides intentional and local.

Decision Guide

• Return plain data when Litestar defaults already match the contract.

• Return Response[T] when the payload is normal but metadata is dynamic.

• Use response_class= when many endpoints need the same serialization strategy.

• Return ASGIApp when wrapping third-party ASGI response objects or custom low-level behavior.

• Use File , Stream , ServerSentEvent , or redirect responses when the transport semantics are special.

• Use subprocess test clients for live-server scenarios the in-process client cannot emulate well, especially infinite SSE streams.

Reference Files

Read only the sections you need:

• For plain typed returns, Response[T] , status codes, layered response_class , custom response classes, and background tasks, read references/response-basics.md.

• For headers, cookies, redirects, files, streams, SSE, templates, and ASGI app returns, read references/response-containers.md.

Recommended Defaults

• Let Litestar serialize normal JSON returns unless you need transport-level control.

• Use status-code constants from litestar.status_codes in both code and tests.

• Document dynamic headers and cookies with documentation_only=True metadata and set the runtime value in the response or hook.

• Keep stream and SSE generators cancellation-safe and bounded by disconnect behavior.

• Keep file delivery and redirect behavior explicit so intermediaries and clients behave predictably.

Anti-Patterns

• Returning Response[Any] everywhere and losing schema precision.

• Using custom response classes when a normal Response[T] or built-in container is enough.

• Returning bodies for 204 No Content endpoints.

• Setting dynamic headers or cookies without documenting them for OpenAPI when clients depend on them.

• Testing infinite stream or SSE behavior only with the in-process client.

• Reimplementing file serving manually instead of using File .

Validation Checklist

• Confirm return annotations match the actual response body and status code.

• Confirm empty-body responses use None annotations and bodies.

• Confirm layered response_class , response_headers , and response_cookies precedence is intentional.

• Confirm dynamic headers and cookies are documented if clients depend on them.

• Confirm stream, SSE, redirect, and file responses have the intended media type and transport behavior.

• Confirm background tasks run only after the response body has been sent.

• Confirm OpenAPI output remains accurate after custom response-class or container changes.

• Confirm response documentation stays aligned with litestar-openapi metadata and examples.

Cross-Skill Handoffs

• Use litestar-exception-handling for error-envelope and failure-response design.

• Use litestar-openapi when response changes materially affect schema output.

• Use litestar-templating for deeper template-engine concerns.

• Use litestar-testing for assertions on status, headers, cookies, streams, redirects, and SSE behavior.

Litestar References

• https://docs.litestar.dev/latest/usage/responses.html

• https://docs.litestar.dev/latest/reference/response/index.html

• https://docs.litestar.dev/latest/usage/testing.html