# Async Routes: When They Help, and When They Don't

An async def route that calls other services with httpx's AsyncClient can ask them all at once with asyncio.gather and give up after a timeout with a 503, while routes with blocking code such as sqlite3 stay plain def, because one blocking call inside async def holds up every request.

Freelancer · FastAPI · REST API · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Write an async def route that calls two services at once with httpx's AsyncClient and asyncio.gather
- Choose between async def and def for a route, and explain why a blocking call inside async def holds up every request
- Give a call to another service a timeout, and answer 503 when that service is slow, down or failing

## Key takeaways

- httpx's AsyncClient calls another service from an async def route. await client.get(url) gives back a response with status_code and json(), the same shape as TestClient's.
- An async def route that awaits two services one after the other takes as long as both. asyncio.gather asks both at once, so the route takes as long as the slower one.
- FastAPI runs async def routes on its event loop and plain def routes in a thread pool, a set of helper threads, so both kinds serve many requests at once.
- Use async def when a route awaits something, such as AsyncClient. Keep blocking code, such as sqlite3 or time.sleep, in plain def routes, or every request waits for it.
- A timeout makes a call give up instead of waiting on and on. Catching httpx.HTTPError turns a service that's slow, down or failing into a clear 503.

The moment an API calls another one, such as a payment company, a map service or a weather service, its routes spend most of their time waiting. Written one way, a single server answers many people while it waits. Written another way, one slow call makes everyone wait. This lesson shows both in FastAPI, and how to tell which way a route should be written.

The example is Movie Night Picker. Its showtimes service and reviews service are stand-ins that each take a second to answer, the same ones *Exercise: Movie Night Picker* hands over, running at `http://127.0.0.1:8001`.

## Calling another service with httpx

httpx sends HTTP requests from Python, and `fastapi[standard]` installs it (`TestClient` is built on httpx2, its newer line, which works the same way). Its `AsyncClient` sends real requests from inside an `async def` route: `await client.get(url)` gives back a response with the same `.status_code` and `.json()` you know from *Testing an API with TestClient*. `async with` opens the client, and closes its connections when the block ends.

```python
import httpx
from fastapi import FastAPI

app = FastAPI(title="Movie Night Picker")

SHOWTIMES_URL = "http://127.0.0.1:8001/showtimes"
REVIEWS_URL = "http://127.0.0.1:8001/reviews"


@app.get("/tonight")
async def tonight():
    async with httpx.AsyncClient() as client:
        showtimes = await client.get(SHOWTIMES_URL)
        reviews = await client.get(REVIEWS_URL)
    return {"showtimes": showtimes.json(), "reviews": reviews.json()}
```

`GET /tonight` answers 200 OK with both lists:

```json
{"showtimes":[{"film_id":1,"title":"Paper Comets","time":"19:00"},{"film_id":2,"title":"The Lighthouse Choir","time":"19:30"},{"film_id":3,"title":"Robot Garden","time":"20:15"},{"film_id":4,"title":"Midnight Noodle Shop","time":"21:00"}],"reviews":[{"film_id":1,"stars":4.2},{"film_id":2,"stars":3.9},{"film_id":3,"stars":4.7},{"film_id":5,"stars":4.9}]}
```

It takes about 2 seconds. As in *async and await in Plain Words*, the route doesn't ask for the reviews until the showtimes are in.

## Both at once with asyncio.gather

`asyncio.gather` sends both requests and waits for both answers together:

```python
@app.get("/tonight")
async def tonight():
    async with httpx.AsyncClient() as client:
        showtimes, reviews = await asyncio.gather(
            client.get(SHOWTIMES_URL),
            client.get(REVIEWS_URL),
        )
    return {"showtimes": showtimes.json(), "reviews": reviews.json()}
```

(It needs `import asyncio` at the top.) The answer is the same, and it now takes about 1 second: as long as the slower service, not both added up. For a page that asks three or four services, that's the difference between a quick page and a slow one.

## async def or def?

FastAPI reads a route's `def` line to decide how to run it:

- An **`async def` route** runs on the **event loop**, the cook from the last lesson, who goes round the pots. While the route awaits an answer, the loop serves other requests.
- A **plain `def` route** runs in a **thread pool**: a set of helper threads FastAPI keeps ready, like extra cooks, each working on one request. A route that waits holds up only its own thread.

Both serve many requests at once. The rule for choosing: **`async def` when the route awaits something** (httpx's `AsyncClient`, `asyncio.sleep`, any package made for async), and **plain `def` when it calls code that blocks** (sqlite3, reading a file, a package with no async version). That's why this course's SQLite routes are plain `def`, as in *A Database Connection for Every Request*: sqlite3 can't be awaited, and the thread pool is the right home for it.

## The mistake that freezes every request

Here are three routes that each take a second, the third with a mistake:

```python
@app.get("/nap/plain")
def nap_plain():
    time.sleep(1)
    return {"route": "def"}


@app.get("/nap/awaits")
async def nap_awaits():
    await asyncio.sleep(1)
    return {"route": "async def"}


@app.get("/nap/blocks")
async def nap_blocks():
    time.sleep(1)
    return {"route": "async def"}
```

Ten requests sent to each route at the same moment came back like this:

| Route | Ten requests at once took |
|---|---|
| `def` with `time.sleep(1)` | about 1 second |
| `async def` with `await asyncio.sleep(1)` | about 1 second |
| `async def` with `time.sleep(1)` | about 10 seconds |

The third route is the trap. `time.sleep` holds the event loop, so the loop can't start the next request until the sleep ends: the tenth caller waits ten seconds. Every other route on the server waits too. In a real app the blocking call is a sqlite3 query, or a plain `httpx.get` inside `async def`. If you can't `await` it, write the route with plain `def`.

![Ten requests arriving at the same moment at two async def routes: in the top lane, the route awaits asyncio.sleep, so the event loop starts all ten and they wait side by side, all finished after about 1 second; in the bottom lane, the route calls time.sleep, so the event loop serves them one at a time, and the tenth finishes after about 10 seconds](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/908a90d950264330ac6db36a1236874d.webp)

## A service that's slow or down

Other services fail: they go down, they get slow, they answer 500. With the stand-ins stopped, `GET /tonight` crashes on the failed connection and answers 500 Internal Server Error. Two changes make it honest:

```python
@app.get("/tonight")
async def tonight():
    try:
        async with httpx.AsyncClient(timeout=2.0) as client:
            showtimes, reviews = await asyncio.gather(
                client.get(SHOWTIMES_URL),
                client.get(REVIEWS_URL),
            )
        showtimes.raise_for_status()
        reviews.raise_for_status()
    except httpx.HTTPError:
        raise HTTPException(status_code=503, detail="A movie service isn't answering. Try again in a few minutes.")
    return {"showtimes": showtimes.json(), "reviews": reviews.json()}
```

- **`timeout=2.0`** gives each request two seconds before httpx stops waiting and raises an error. Without it, httpx waits five seconds at each step.
- **`raise_for_status()`** raises an error when a service answers 400 or above, such as its own 500.
- **`except httpx.HTTPError`** catches all three ways a call fails: no connection, a timeout, and an error status.

With the stand-ins stopped, `GET /tonight` now answers 503 Service Unavailable, which means "I can't do that right now, try again later", in the API's one error shape from *One Error Shape for the Whole API*:

```json
{"status":503,"title":"Service Unavailable","detail":"A movie service isn't answering. Try again in a few minutes."}
```

With the stand-ins taking three seconds to answer, it gives up after two and sends the same 503.

## Check yourself

2 questions to try on the lesson page.

## So what

An `async def` route that awaits its services together answers in the time of the slowest one, a plain `def` route keeps blocking code from freezing the server, and a timeout with a 503 turns another service's bad day into an honest answer.

## Key terms

- [async def](https://www.ask-codey.com/glossary/async-def)
- [Event Loop and Blocking Calls](https://www.ask-codey.com/glossary/event-loop-and-blocking-calls)
- [httpx](https://www.ask-codey.com/glossary/httpx)
- [Timeout](https://www.ask-codey.com/glossary/timeout-rest-api)
- [503 Service Unavailable](https://www.ask-codey.com/glossary/503-service-unavailable)

## Related

- [async and await in Plain Words](https://www.ask-codey.com/lessons/fastapi-async-await-plain-words)
- [Work That Runs After the Response](https://www.ask-codey.com/lessons/fastapi-background-tasks)
- [A Database Connection for Every Request](https://www.ask-codey.com/lessons/fastapi-data-get-db-dependency)

Source: https://www.ask-codey.com/lessons/fastapi-async-routes-when-they-help
