Update error handling docs, including Starlette's utils (#41)

:memo: Update error handling docs, including Starlette's utils

diff --git a/docs/release-notes.md b/docs/release-notes.md
index 3175c7aa48da5bb57e8b20634bb10c4bd285bb63..b078cb1e7ec732827097e1c3a1d4603cc52e69ac 100644 (file)
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -4,6 +4,8 @@
 
 * Add note about <a href="https://fastapi.tiangolo.com/tutorial/path-params/#order-matters" target="_blank">path operations order in docs</a>.
 
+* Update <a href="https://fastapi.tiangolo.com/tutorial/handling-errors/" target="_blank">section about error handling</a> with more information and make relation with Starlette error handling utilities more explicit. PR <a href="https://github.com/tiangolo/fastapi/pull/41" target="_blank">#41</a>.
+
 ## 0.5.0
 
 * Add new `HTTPException` with support for custom headers. With new documentation for handling errors at: <a href="https://fastapi.tiangolo.com/tutorial/handling-errors/" target="_blank">https://fastapi.tiangolo.com/tutorial/handling-errors/</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/35" target="_blank">#35</a>.

diff --git a/docs/src/handling_errors/tutorial003.py b/docs/src/handling_errors/tutorial003.py
new file mode 100644 (file)
index 0000000..8e14305
--- /dev/null
+++ b/docs/src/handling_errors/tutorial003.py
@@ -0,0 +1,15 @@
+from fastapi import FastAPI
+from starlette.exceptions import HTTPException
+from starlette.responses import PlainTextResponse
+
+app = FastAPI()
+
+
+@app.exception_handler(HTTPException)
+async def http_exception(request, exc):
+    return PlainTextResponse(str(exc.detail), status_code=exc.status_code)
+
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}

diff --git a/docs/tutorial/handling-errors.md b/docs/tutorial/handling-errors.md
index d371f20c1354cf9ec5ca05fe4c0244e069606b8c..1c143da29a74bc041609681237dbc2de2c7c62ac 100644 (file)
--- a/docs/tutorial/handling-errors.md
+++ b/docs/tutorial/handling-errors.md
@@ -43,6 +43,31 @@ In this example, when the client request an item by an ID that doesn't exist, ra
 {!./src/handling_errors/tutorial001.py!}
 ```
 
+### The resulting response
+
+If the client requests `http://example.com/items/foo` (an `item_id` `"foo"`), he will receive an HTTP status code of 200, and a JSON response of:
+
+```JSON
+{
+  "item": "The Foo Wrestlers"
+}
+```
+
+But if the client requests `http://example.com/items/bar` (a non-existent `item_id` `"bar"`), he will receive an HTTP status code of 404 (the "not found" error), and a JSON response of:
+
+```JSON
+{
+  "detail": "Item not found"
+}
+```
+
+!!! tip
+    When raising an `HTTPException`, you can pass any value that can be converted to JSON as the parameter `detail`, not only `str`.
+
+    You could pass a `dict`, a `list`, etc.
+
+    They are handled automatically by **FastAPI** and converted to JSON.
+
 ### Adding custom headers
 
 There are some situations in where it's useful to be able to add custom headers to the HTTP error. For example, for some types of security.
@@ -55,3 +80,20 @@ But in case you needed it for an advanced scenario, you can add custom headers:
 ```Python hl_lines="14"
 {!./src/handling_errors/tutorial002.py!}
 ```
+
+### Installing custom handlers
+
+If you need to add other custom exception handlers, or override the default one (that sends the errors as JSON), you can use <a href="https://www.starlette.io/exceptions/" target="_blank">the same exception utilities from Starlette</a>.
+
+For example, you could override the default exception handler with:
+
+```Python hl_lines="2 3 8 9 10"
+{!./src/handling_errors/tutorial003.py!}
+```
+
+...this would make it return "plain text" responses with the errors, instead of JSON responses.
+
+!!! info
+    Note that in this example we set the exception handler with Starlette's `HTTPException` instead of FastAPI's `HTTPException`.
+
+    This would ensure that if you use a plug-in or any other third-party tool that raises Starlette's `HTTPException` directly, it will be catched by your exception handler.