← All notes

Answer: To return HTTP responses with errors to the client you use HTTPException. Because it's a Python exception, you don't return it, you raise it. (S1)

Details and handlers

• When raising an HTTPException, you can pass any value that can be converted to JSON as the parameter detail, not only str. (S1)
• The status codes in the 400 range mean that there was an error from the client. (S1)
• When a request contains invalid data, FastAPI internally raises a RequestValidationError. (S1)
• Default handlers are in charge of returning the default JSON responses when you raise an HTTPException and when the request has invalid data. (S1)

Status codes

• The status_code parameter receives a number with the HTTP status code. (S2)
• status_code can alternatively also receive an IntEnum, such as Python's http.HTTPStatus. (S2)
• Some response codes indicate that the response does not have a body. (S2)

Claims

• id: C1 claim: Use HTTPException for errors. source: S1 evidence: "To return HTTP responses with errors to the client you use HTTPException."
• id: C2 claim: You raise it rather than return it. source: S1 evidence: "you don't return it, you raise it."
• id: C3 claim: Invalid data raises RequestValidationError. source: S1 evidence: "FastAPI internally raises a RequestValidationError."
• id: C4 claim: status_code can be an IntEnum. source: S2 evidence: "status_code can alternatively also receive an IntEnum"

Sources

• [S1] Handling Errors - FastAPI. FastAPI docs. https://fastapi.tiangolo.com/tutorial/handling-errors/ . License: MIT (fastapi/fastapi LICENSE; Copyright (c) 2018 Sebastián Ramírez; https://github.com/fastapi/fastapi/blob/master/LICENSE). Accessed 2026-11-04.
• [S2] Response Status Code - FastAPI. FastAPI docs. https://fastapi.tiangolo.com/tutorial/response-status-code/ . License: MIT (fastapi/fastapi LICENSE; Copyright (c) 2018 Sebastián Ramírez; https://github.com/fastapi/fastapi/blob/master/LICENSE). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_nrhxedet,
  author = {{iinventedlight}},
  title = {{Returning HTTP errors in FastAPI}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/fastapi-error-handling/},
  note = {Permanent ID iil:note:nrhxedet. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/fastapi-error-handling.md.