What the response actually promises
Sending an HTTP response before finishing work can make an interface feel responsive. It also creates a new question: what survives if the application process stops immediately afterward? An in-process background task and a durable job queue provide different recovery properties. Choose according to the business promise rather than the convenience of an API call.
FastAPI documents BackgroundTasks for work performed after a response and points to larger worker tools for heavier or multi-process work. This guide does not declare every small background task unsafe. It asks whether the application needs durable acceptance, retries, status visibility or recovery after a restart.
Setup: define the job state model
List the operation, expected duration, side effects and failure owner. Decide whether the user sees accepted, processing, completed or failed. If the interface says a report is ready, the report must actually be ready. If it says accepted, provide a meaningful status reference and define the recovery expectation.
For durable work, establish where the job record and payload are stored, how workers authenticate, and how duplicate attempts are recognized. Keep secrets and large sensitive documents out of unrestricted queue payloads. A job reference can point to protected data whose access is checked by the worker.
Illustrative incident: a restart loses the receipt
An illustrative service accepts a document-generation request and schedules it inside the web process. A deployment restarts that process before the document is produced. The user has a successful response but no recoverable job record. This teaching scenario is not a reported customer incident.
Reproduce with a synthetic task paused after the response. Restart the worker and inspect whether the system can identify unfinished work. A log line saying task scheduled is not durable acceptance evidence unless the log itself is the deliberately designed job system, with the required recovery semantics.
Troubleshooting: identify the missing guarantee
| Symptom | Evidence | Boundary |
|---|---|---|
| Work disappears during restart | Job persistence and process lifecycle | Is acceptance durable? |
| User cannot tell what happened | State transitions and status endpoint | Is job ownership visible? |
| Retry creates duplicate output | Operation identity and effect records | Is execution idempotent? |
| Web requests slow during heavy jobs | CPU, memory and worker isolation | Is compute competing with request handling? |
Do not add unlimited retries to an operation that can charge, send or modify external state. First establish whether a previous attempt committed its effect. Recovery may require reconciliation rather than immediate replay.
Corrective action by workload class
Keep simple best-effort in-process work where that contract is acceptable and observable. Move durable or resource-intensive work into an appropriately managed worker system with admission limits and explicit state. The queue is only one component: define worker shutdown, visibility, retry backoff and a destination for terminal failures.
Persist acceptance before telling the caller that a durable job exists. Design the database-to-queue transition so a failure cannot silently lose the job; an outbox or another reviewed consistency mechanism may be appropriate. Give operators a controlled replay action that records who retried what and why, rather than requiring them to edit database rows manually.
Verification, completion SLO and SOP
Test process restart before work begins, failure during work, duplicate delivery and completion followed by a lost acknowledgment. Confirm that the user sees an accurate state and that completed effects are not repeated. Measure queue age and business completion separately from HTTP request latency.
An internal SLO should concern eligible jobs reaching a valid terminal state within the agreed envelope. A contractual SLA needs its own workload and dependency assumptions. The SOP should identify the job owner, restart behavior, retry limit, failure queue and reconciliation procedure. Avoid reporting accepted requests as successful business completions in dashboards.
Explore software development and DevOps automation.
Technical reference
FastAPI background tasks, reviewed 19 October 2026. Follow documentation matching the installed product version.