Please add additional documentation on returning status code 204 ("Too much data for declared Content-Length" error)

[peterwwillis]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

# Sample code provided in links in description

Description

Hello,

In FastAPI, if you develop a function which should return status code 204, you may end up encountering this error:

h11._util.LocalProtocolError: Too much data for declared Content-Length

The problem, as I understand it, is this:

1. FastAPI (or Starlette? not really sure where it's happening) is taking the response object from the function (or defaulting to a specific response object) and deciding whether or not to return a body, in addition to the specific status code requested
2. The HTTP library being used to serve requests is strictly checking the body against the returned status code, and if they conflict, throws an exception
3. FastAPI does not check whether the combination of body and status code would violate the HTTP spec
4. Based on the error message, is not apparent why the exception is being thrown, and it is not apparent how to solve this problem with FastAPI

Similar issues have been found here:

• h11._util.LocalProtocolError: Too much data for declared Content-Length - when returning dict as response, with custom status code #7187
• default HTTPException handler adds content when there should be none #8499
• How to send 204 response? #8010

There is an answer given on the first discussion to use a decorator (ex. @app.get("/", status_code=204)), but in my case I was using app.add_api_route() and thus not sure how to add a status code. And as another commenter says, they need to return different status codes depending on some logic, and it wasn't apparent how to do that and avoid error. (when I did try to switch to using a decorator, the app returned a 422 status and error message with some Pydantic json blob, rather than the 204 status I was hoping for, but maybe that's some other problem?)

The "correct" solution appears to be to change one's code to return a Response(status_code=HTTPStatus.NO_CONTENT.value), rather than a JSONResponse("", status_code=204) or HTTPResponse. This avoids whatever extra processing is adding extra bytes in the response.

My request is that the documentation (here and here) be updated to include instructions to use the Response for HTTP 204 status codes, with either a brief explanation of the issue or a link to this discussion. Based on the number of other issues, and my own time trying to track down a solution for this, I think this additional documentation would save people a fair bit of time.

It would be nice if the JSONResponse/HTTPResponse/etc knew not to return a body for status code 204 (or whatever additional processing it's doing; just returning None or "" as the body seems to still cause the error), but I'm not trying to make more work for anybody.

Thanks very much for your consideration 🙏

---

(p.s. servers which don't use h11, like hypercorn(?), don't hit this error, which is interesting; some people might be running into this bug and just not knowing it because their server's http library isn't as robust)

Operating System

Linux

Operating System Details

No response

FastAPI Version

0.104.1

Pydantic Version

2.5.1

Python Version

Python 3.11.6

Additional Context

No response

[YuriiMotov]

Solution: #8010 (comment)

Thanks for the idea! We will consider adding this clarification in docs