Report missing resources
A requested resource does not exist.
FastAPI · Class
HTTPException
FastAPI's HTTPException is raised to send a deliberate client-facing HTTP error. It accepts a status code plus optional JSON-compatible detail data and response headers.
How it works
HTTPException is a FastAPI exception for terminating a request with an HTTP error response. Construct it with a status code and optionally include JSON-compatible detail data and response headers, then raise it rather than returning it.
Syntax
HTTPException(status_code, detail=None, headers=None)Parameters
| Name | Type | Description |
|---|---|---|
status_code | int | HTTP status code to send to the client. |
detail | Any | Data sent in the JSON response's detail key; defaults to None. |
headers | Mapping[str, str] | None | Headers sent in the response; defaults to None. |
Returns
An exception instance to raise; raising it produces the client-facing HTTP error response.
Key points
- Raise the class in application code when an endpoint needs to return a deliberate HTTP error.
- status_code is the required argument and determines the HTTP response status.
- detail is placed under the response's detail key and may contain more than a plain string.
- headers lets the exception add response headers, with values represented as strings.
- Import HTTPException directly from the fastapi package.
- Raising the exception immediately ends the remaining execution for that request.
Common mistakes
- Use raise, not return, because HTTPException is an exception and raising it stops the current request immediately.
- Use this class for client-side problems such as invalid input or authentication failures, not unexpected application bugs.
Example: Raise an HTTP error from a path operation
from fastapi import FastAPI, HTTPException
app = FastAPI()
items = {"foo": "The Foo Wrestlers"}
@app.get("/items/{item_id}")
async def read_item(item_id: str):
if item_id not in items:
raise HTTPException(status_code=404, detail="Item not found")
return {"item": items[item_id]}Raises a client-facing 404 response when the requested item is absent.
When to use it
Reject invalid client requests
A request contains invalid data or credentials.
Add authentication response headers
The client must receive an authentication challenge header.
Interview questions
QWhat is HTTPException used for?
HTTPException represents an API error that FastAPI converts into an HTTP response. Its constructor accepts a status code, optional detail payload, and optional headers.
Follow-up: Can detail be structured data? Yes. FastAPI accepts values that can be converted to JSON, including dictionaries and lists.
QHow do you send a custom error from an endpoint?
Raise it with the desired HTTP status code and a message or other JSON-compatible value in detail. FastAPI then sends that information in the response's detail field.
Follow-up: What happens after it is raised? Execution of the current request is aborted, so later code in that path operation does not run.
QHow does FastAPI's HTTPException differ from Starlette's?
FastAPI's class inherits from Starlette's HTTPException but permits any JSON-compatible detail value, whereas Starlette's version only accepts strings for detail.
Follow-up: What can headers provide? They can add response headers such as WWW-Authenticate for authentication-related errors.
Related
WebSocketExceptionfastapi.exceptions.HTTPException