tsayin4 · Oct 6, 2026
diff --git a/docs/en/docs/tutorial/background-tasks.md b/docs/en/docs/tutorial/background-tasks.md
@@ -45,6 +45,32 @@ Inside of your *path operation function*, pass your task function to the *backgr
 * Any sequence of arguments that should be passed to the task function in order (`email`).
 * Any keyword arguments that should be passed to the task function (`message="some notification"`).
 
+## Handle errors in the task { #handle-errors-in-the-task }
+
+The background task runs **after** the response is sent, so an exception inside it cannot change a
+response that has already gone out. It is not propagated to the *path operation function* either, which
+means a task can fail without anything in the response or the client suggesting that it did.
+
+That is the expected behavior, but it is easy to miss: the caller sees `200 OK` whether or not the
+notification was written.
+
+If the task does something you need to know about, catch the error inside the task and record it:
+
+{* ../../docs_src/background_tasks/tutorial003_py310.py hl[7,11:14] *}
+
+Logging is the smallest version of this. Depending on what the task does, you might also retry it, alert
+whoever is on call, or store the failure so it can be looked at later.
+
+/// tip
+
+For background work that has to survive a restart, be retried, or run on a different machine, use a task
+queue like <a href="https://docs.celeryq.dev" class="external-link" target="_blank">Celery</a>,
+<a href="https://arq-docs.helpmanual.io/" class="external-link" target="_blank">arq</a>, or
+<a href="https://dramatiq.io/" class="external-link" target="_blank">Dramatiq</a>. The
+[Caveat](#caveat) section below describes when `BackgroundTasks` stops being enough.
+
+///
+
 ## Dependency Injection { #dependency-injection }
 
 Using `BackgroundTasks` also works with the dependency injection system, you can declare a parameter of type `BackgroundTasks` at multiple levels: in a *path operation function*, in a dependency (dependable), in a sub-dependency, etc.

diff --git a/docs_src/background_tasks/tutorial003_py310.py b/docs_src/background_tasks/tutorial003_py310.py
@@ -0,0 +1,25 @@
+import logging
+
+from fastapi import BackgroundTasks, FastAPI
+
+app = FastAPI()
+
+logger = logging.getLogger(__name__)
+
+
+def send_notification(email: str):
+    try:
+        write_notification(email)
+    except Exception:
+        logger.exception("Could not send the notification to %s", email)
+
+
+def write_notification(email: str):
+    with open("log.txt", mode="w") as email_file:
+        email_file.write(f"notification for {email}")
+
+
+@app.post("/send-notification/{email}")
+async def send_notification_endpoint(email: str, background_tasks: BackgroundTasks):
+    background_tasks.add_task(send_notification, email)
+    return {"message": "Notification sent in the background"}
diff --git a/tests/test_tutorial/test_background_tasks/test_tutorial003.py b/tests/test_tutorial/test_background_tasks/test_tutorial003.py
@@ -0,0 +1,39 @@
+import logging
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+from fastapi.testclient import TestClient
+
+from docs_src.background_tasks import tutorial003_py310
+from docs_src.background_tasks.tutorial003_py310 import app
+from tests.utils import workdir_lock
+
+client = TestClient(app)
+
+
+@workdir_lock
+def test():
+    log = Path("log.txt")
+    if log.is_file():
+        os.remove(log)  # pragma: no cover
+    response = client.post("/send-notification/foo@example.com")
+    assert response.status_code == 200, response.text
+    assert response.json() == {"message": "Notification sent in the background"}
+    with open("./log.txt") as f:
+        assert "notification for foo@example.com" in f.read()
+
+
+@workdir_lock
+def test_a_failing_task_is_logged_and_leaves_the_response_alone(caplog):
+    # this is the behaviour the section documents: the response is already out, so the failure can
+    # only be seen if the task records it
+    with patch.object(
+        tutorial003_py310, "write_notification", side_effect=OSError("disk full")
+    ):
+        with caplog.at_level(logging.ERROR):
+            response = client.post("/send-notification/foo@example.com")
+
+    assert response.status_code == 200, response.text
+    assert response.json() == {"message": "Notification sent in the background"}
+    assert "Could not send the notification to foo@example.com" in caplog.text