FastAPI Document Jobs: Return an Accepted Request, Not an Imaginary Result

A document-generation API should distinguish accepting a request from producing a usable file. Return a completed result only when the file satisfies the application's completion contract. Otherwise, give the client a durable operation to follow.

FastAPI's background-task guide describes work performed after a response and notes that heavier distributed computation may need a separate job system. The implementation choice should follow the reliability and workload requirements, not only the desire for a quick response.

Define the generation request

Identify the template or design version, input data, output format and account that owns the result. A request that references a mutable template needs a clear rule about which version will be rendered.

thirds.ai, declared in the FastAPI catalogue, describes turning designs into branded PDFs and images. The example below uses that workflow category without assuming the product's internal queue or rendering implementation.

For your own API, preserve enough request identity to explain the resulting file later.

Make acceptance durable

Before reporting that a job was accepted, ensure the system has recorded the work it promises to perform. An in-memory task scheduled on one process may not satisfy a promise to survive restart.

Return an operation identifier and a documented status location. The client should be able to leave the original connection and still find the outcome.

Keep validation failures separate from accepted jobs. Invalid input that never entered the workflow should not look like a long-running operation.

Describe useful states

A small state model might distinguish waiting, rendering, completed and failed. Add states only when they change what the user or operator can do.

For failure, explain whether input needs correction, a dependency is temporarily unavailable or a retry is already scheduled. Avoid exposing private renderer diagnostics in the public response.

For completion, verify that the result is stored and accessible to the intended owner. A generated byte stream that was never durably delivered may not meet the product's promise.

Reconcile repeated requests

Clients retry after connection loss. Decide whether the same operation should return the existing job or intentionally create another document.

Where supported, use a stable idempotency reference tied to the relevant request content. Reusing a key for different content should have a defined conflict response rather than silently producing an unexpected file.

Keep billing or usage accounting consistent with the operation's actual outcome. This is a design requirement to verify, not a claim about any provider's pricing behavior.

Review output access and retention

A result URL may be public, authenticated or time-limited. Choose the model deliberately and explain expiry to clients.

If a download link expires before the file's retention period ends, offer a documented way to obtain a fresh authorized link. Do not require regeneration merely because a delivery credential expired.

Test an interrupted render, a duplicate request and an expired result link with synthetic documents. Inspect the job record, file count and public response together.

The FastAPI response-model guide helps define the safe fields for these states. A good asynchronous endpoint makes waiting and recovery explicit instead of disguising unfinished work as success.