Error handling with HTTPException

To return HTTP error responses to the client, raise HTTPException — imported from fastapi — rather than returning it: it is a normal Python exception with additional data relevant for APIs, as in raise HTTPException(status_code=404, detail="Item not found"). Raising from anywhere in the call chain, including a utility function called by the path operation, terminates that request right away and sends the error to the client without running the rest of the path operation code. The detail parameter accepts any value that can be converted to JSON — not only str, but dict and list — and FastAPI handles the conversion automatically. When an error needs custom headers, for example for some types of security, pass headers={"X-Error": "There goes my error"}; the tutorial notes you probably won't need this directly in everyday code. For exceptions of your own, install a global custom exception handler with @app.exception_handler(), using the same exception utilities from Starlette, and return a JSONResponse. Scope: FastAPI. Reviewed October 4, 2026.