BFF Aggregation, Timeouts and Partial Failure
On this page
The weakest-link problem
Day 2's dashboard endpoint called the tasks API and the recommendations service with Promise.all. It's fast when both are healthy. But Promise.all rejects as soon as *either* call fails, and waits as long as the slowest one takes. Recommendations are a nice extra. Tasks are the reason the page exists. Today a recommendations outage takes the whole dashboard down with it.
Before writing the endpoint, decide for each dependency what happens if it fails:
| Data | If it fails | If it's slow |
|---|---|---|
| Tasks | The dashboard can't work: return an error | Wait up to 1 second |
| Recommendations | Show the page without them | Give up after 300 ms |
This is a product decision as much as an engineering one, so agree on it with whoever owns the screen.
Give every call a timeout
fetch has no timeout by default. A downstream service that hangs makes your BFF hang, holding a connection and memory for each waiting user. AbortSignal.timeout adds a deadline in one line:
const res = await fetch(url, { signal: AbortSignal.timeout(300) });
// if 300 ms pass first, fetch rejects with an error named 'TimeoutError'In a test against a service that took two seconds, the call failed with TimeoutError after 302ms. Pick each timeout from the service's normal latency, for example a bit above its 99th percentile, and from how long the user can reasonably wait.
Use allSettled for optional data
Promise.allSettled waits for every promise and tells you which succeeded, instead of failing on the first problem:
app.get('/bff/dashboard', async (req, reply) => {
const session = await requireSession(req, reply);
if (!session) return;
const token = await accessTokenOnce(session);
const [tasks, recs] = await Promise.allSettled([
getJson(`${TASKS_API}/tasks`, { token, timeoutMs: 1000 }),
getJson(`${RECS_API}/recs`, { timeoutMs: 300 }),
]);
if (tasks.status === 'rejected') {
req.log.error({ err: tasks.reason }, 'tasks unavailable');
return reply.code(502).send({ error: 'Tasks are unavailable right now.' });
}
return {
user: { name: session.data.user.name },
tasks: tasks.value.items.map((t: Task) => ({ id: t.id, title: t.title, done: t.done })),
recommendations: recs.status === 'fulfilled' ? recs.value.items : [],
degraded: recs.status === 'rejected' ? ['recommendations'] : [],
};
});
async function getJson(url: string, opts: { token?: string; timeoutMs: number }) {
const res = await fetch(url, {
headers: opts.token ? { authorization: `Bearer ${opts.token}` } : {},
signal: AbortSignal.timeout(opts.timeoutMs),
});
if (!res.ok) throw Object.assign(new Error(`HTTP ${res.status}`), { status: res.status });
return res.json();
}With the recommendations service slowed to 800 ms, the lab returned in about 300 ms instead of failing:
{"user":{"name":"Ada Lovelace"},"tasks":[...],"recommendations":[],"degraded":["recommendations"],"tookMs":305}Tell the client what's missing
The degraded array matters. Without it, an empty recommendations list is ambiguous: does Ada have no recommendations, or is the service down? With it, the React app can show "Suggestions are unavailable right now" instead of an empty panel, and your monitoring can count degraded responses.
Return 200 for a degraded but useful response. Return 502 Bad Gateway when a *required* dependency fails, since the problem is upstream of the BFF, or 504 Gateway Timeout if it timed out.
Shape the response for the screen
Aggregation is also where the BFF earns its "for frontend" name. Map each downstream object to exactly what the screen shows:
- drop internal fields like
ownerand audit columns, - rename awkward fields once, here, rather than in every component,
- format nothing that the browser can format better: send ISO dates and numbers, and let the app localize them.
Watch payload size. A BFF that returns everything "just in case" ends up as slow as the API it replaced.
Avoid accidental sequential calls
Calls that depend on each other must run in order, like fetching a project and then its members. But calls that look dependent often aren't. Compare:
// slow: 3 round trips one after another
const user = await getUser(id);
const tasks = await getTasks(id);
const recs = await getRecs(id);
// fast: start everything that only needs the id at once
const [user, tasks, recs] = await Promise.allSettled([getUser(id), getTasks(id), getRecs(id)]);When a list needs details per item, don't make one call per item (the "N+1" problem). Ask the owning service for a batch endpoint like GET /users?ids=1,2,3.
Check yourself
Promise.all rejects as soon as any promise fails and waits as long as the slowest one takes. So an outage or slowdown in an optional service like recommendations takes the whole dashboard down with it. Promise.allSettled waits for every call and reports each result separately, so optional parts can fail on their own.
The BFF includes a degraded list naming the parts that failed, so the app can show a "temporarily unavailable" message instead of an empty panel.
502 Bad Gateway, or 504 Gateway Timeout if the call timed out. Both say the failure happened in a dependency behind the BFF, not in the request itself. That helps monitoring point at the right service, and tells the client a retry later might succeed.
fetch has no default timeout, so every request that calls the service waits indefinitely, holding a connection and memory. Under load the BFF runs out of resources and fails for every user, including on routes that don't use that service. AbortSignal.timeout on every downstream call prevents this.
Only if you already know the project id. If the members call needs data from the project response, they must run in order. But many calls that look dependent only need the id from the URL, so start everything that can start at once, and ask for batch endpoints instead of one call per item.