Request Body Limits¶
Warning
This page hasn’t been translated into your language yet. 🌍
We’re currently switching to an automated translation system 🤖, which will help keep all translations complete and up to date.
Learn more: Contributing - Translations
Imagine your app receives small JSON requests, but you also want to let users upload larger files.
You can set max_body_size in bytes when you create your FastAPI app. Then you can set a different limit for an APIRouter or for a single path operation.
from fastapi import APIRouter, FastAPI, UploadFile
app = FastAPI(max_body_size=1 * 1024 * 1024)
uploads = APIRouter(prefix="/uploads", max_body_size=100 * 1024 * 1024)
@app.post("/items")
def create_item(item: dict):
return item
@uploads.post("/")
def upload(file: UploadFile):
return {"filename": file.filename, "size": file.size}
@uploads.post("/small", max_body_size=10 * 1024 * 1024)
def small_upload(file: UploadFile):
return {"filename": file.filename, "size": file.size}
app.include_router(uploads)
POST /itemsuses the app's limit of 1 MiB (1024 * 1024bytes).POST /uploads/uses the router's limit of 100 MiB.POST /uploads/smallhas its own limit of 10 MiB.
What counts toward the limit?¶
The limit applies to the whole request body. If you upload two files in the same request, both files, any form fields, and the bytes used to encode the multipart form all count toward that one limit. The URL and request headers are outside the body.
FastAPI counts the bytes it reads, even if the client sends the body in chunks without a Content-Length header. If a read exceeds the limit, FastAPI stops reading and returns an HTTP 413 Content Too Large response if the response hasn't started yet.
If your path operation reads the body itself, it can start running before FastAPI knows the total size. For example, if you're streaming an upload to a temporary file, finish reading it before you publish the file.
With UploadFile, a file can move from memory to disk as it grows. Its contents still count toward the same limit.
Set a default for a router¶
You can also pass max_body_size to include_router(). The included router uses that default unless it declares its own limit. A path operation can always declare a smaller or larger limit of its own.
If you leave max_body_size at its default of None, it inherits the limit from the router or app that contains it. Mounted apps inherit the parent app's limit in the same way. If you don't set a limit anywhere, FastAPI leaves the body size unlimited. Use a positive integer for the number of bytes, or 0 to allow only an empty body.
Middleware that reads the body
If your middleware reads the body before FastAPI selects a path operation, the app's limit applies to that read. In the example above, middleware that calls await request.body() would reject a 2 MiB upload before it reaches the router that allows 100 MiB.
If the middleware passes the request to a mounted app, the mounted app's limit also applies to the bytes already read.
If your middleware needs to read those uploads, set the app's limit large enough for them and set smaller limits on the path operations that need them.
Set limits for form fields and files¶
You can set limits for form fields and files in the form_limits configuration.
Each setting inherits independently, so you can override just the limits you need on the app, on a router, in include_router(), or on a single path operation.
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI(form_limits={"max_fields": 5})
@app.post("/notes")
async def create_note(text: Annotated[str, Form()]):
return {"size": len(text)}
@app.post("/documents", form_limits={"max_part_size": 2 * 1024 * 1024})
async def create_document(text: Annotated[str, Form()]):
return {"size": len(text)}
max_fieldssets the maximum number of text fields. The default is 1,000.max_filessets the maximum number of files in a multipart form. The default is 1,000.max_part_sizesets the maximum size in bytes of each text field. The default is 1 MiB. For URL-encoded forms, Starlette counts the encoded name and value together.
FastAPI passes these settings to Starlette when it parses a request for a Form, File, or UploadFile parameter, including parameters in dependencies. Exceeding a parser limit returns HTTP 400. Use max_body_size to bound the whole request, including uploaded file contents.
If you parse a form yourself, pass your limits to the first request.form() call. Starlette caches the parsed form on that request.