Promise.all Is Not a Concurrency Limit: Bound API Fan-Out
Limit API fan-out with a tested JavaScript worker pool that preserves result order, records failures, and bounds active tasks.

Quick answer
Promise.all() waits for a group of promises; it does not limit how many operations your code starts. To bound API fan-out, pass unstarted work to a small pool of workers and let each worker start its next task only after the previous task settles. Decide separately how to handle errors, timeouts, cancellation, and requests-per-second quotas.
A dashboard loads shipping quotes for hundreds of orders. The first version uses await Promise.all(ids.map(loadQuote)). It works in a small fixture, then produces a burst of upstream failures in production. The map callback calls loadQuote for every ID immediately. If loadQuote starts a fetch, the application has already started all those operations before Promise.all can await them.
Locate where the work starts
Inspect the function call that creates each promise. Passing an array of already-started fetch promises into a limiter is too late to control their start rate. Pass IDs, URLs, or task functions instead, and make the limiter invoke the operation when a worker is free.
Promise.all returns values in input order and rejects when an input promise rejects. That rejection does not cancel the other operations. MDN's Promise.all reference describes the aggregation behavior. For a quote dashboard, partial results may be more useful than discarding every successful quote because one provider failed.
The implementation below deliberately collects one outcome per input. Its result shape resembles Promise.allSettled: each slot contains either a fulfilled value or a rejected reason. Changing from Promise.all to Promise.allSettled alone would still not limit the work that an eager map starts.
Run a small worker pool with assertions
Save the following as concurrency-lab.mjs and run node concurrency-lab.mjs with a supported Node.js installation. It uses only built-in modules and makes no network calls. The mock task yields to the event loop so several tasks remain active together; one task takes an extra turn and another fails. Node's timers documentation documents the promise-based scheduling primitive used by the fixture.
import assert from 'node:assert/strict'
import { setImmediate as yieldTurn } from 'node:timers/promises'
async function mapSettledWithLimit(items, limit, task) {
if (!Array.isArray(items) || typeof task !== 'function') {
throw new TypeError('Expected an array and a task function')
}
// A teaching-policy cap, not a universal recommendation for API capacity.
if (!Number.isInteger(limit) || limit < 1 || limit > 32) {
throw new RangeError('Limit must be an integer from 1 to 32')
}
const input = items.slice()
const results = new Array(input.length)
let next = 0
async function worker() {
while (next < input.length) {
const index = next++ // Claim synchronously before the first await.
try {
const value = await task(input[index], index)
results[index] = { status: 'fulfilled', value }
} catch (reason) {
results[index] = { status: 'rejected', reason }
}
}
}
await Promise.all(Array.from({ length: Math.min(limit, input.length) }, worker))
return results
}
let active = 0
let peak = 0
const completed = []
const results = await mapSettledWithLimit([1, 2, 3, 4, 5], 3, async id => {
active += 1
peak = Math.max(peak, active)
try {
await yieldTurn()
if (id === 1) await yieldTurn() // Finish out of input order.
if (id === 3) throw new Error('Demo upstream failure')
return id * 10
} finally {
completed.push(id)
active -= 1
}
})
assert.equal(peak, 3)
assert.equal(active, 0)
assert.notDeepEqual(completed, [1, 2, 3, 4, 5])
assert.deepEqual(results.map(r => r.status), [
'fulfilled', 'fulfilled', 'rejected', 'fulfilled', 'fulfilled',
])
assert.deepEqual(results.filter(r => r.status === 'fulfilled').map(r => r.value), [10, 20, 40, 50])
assert.equal(results[2].reason.message, 'Demo upstream failure')
assert.deepEqual(await mapSettledWithLimit([], 3, () => assert.fail('Unexpected call')), [])
assert.deepEqual(await mapSettledWithLimit([7], 32, n => n), [{ status: 'fulfilled', value: 7 }])
const syncFailure = await mapSettledWithLimit([1], 1, () => { throw new Error('sync') })
assert.equal(syncFailure[0].status, 'rejected')
for (const limit of [0, -1, 1.5, 33, NaN]) {
await assert.rejects(mapSettledWithLimit([1], limit, n => n), RangeError)
}
console.log(`Peak active tasks: ${peak}`)
console.log('Results: 10, 20, rejected, 40, 50')
console.log('All concurrency, ordering, and failure checks passed.')Expect three output lines: Peak active tasks: 3, Results: 10, 20, rejected, 40, 50, and All concurrency, ordering, and failure checks passed. The assertions verify the actual peak, an empty input, fewer items than workers, invalid limits, synchronous throws, asynchronous rejection, and stable result positions. They do not depend on a particular number of elapsed milliseconds.
The function copies the input array so changing its length outside the pool will not change the work list. This is a shallow copy; callers must still avoid unexpected mutation of objects referenced by the array. The cap of 32 is an explicit teaching-policy guard, not a recommendation for your provider's capacity.
Why the bound holds
There are at most limit workers. Each worker claims one index, invokes one task, and awaits it before claiming another. No worker holds two unfinished task calls at once. The index increment happens synchronously before an await, so these async workers in one JavaScript execution context do not claim the same index. This is not a cross-thread or cross-process queue.
Results are stored at the claimed index rather than appended as tasks finish. That keeps the failed third quote attached to the third input even when the first quote is slow. Use the index or a stable identifier to associate each outcome with the original row; otherwise a correct concurrency limit can still produce an incorrect UI.
This guarantee depends on the task returning a promise that covers all its work. A task that launches a fetch in the background and returns immediately releases its slot too early. A task that launches ten requests internally can create up to ten times the intended network fan-out. Define what one task owns, and keep that boundary consistent.
Wrap the complete request lifecycle
When replacing the fixture with loadQuote, keep the fetch, status check, body read, and decoding inside the returned async operation. Fetch does not reject merely because the response has an HTTP error status: inspect response.ok and classify the status yourself. Awaiting only the response headers and parsing the body outside the task can also release a slot before the operation you intended to bound has finished. See MDN's Fetch guide.
Give each real request a timeout or deadline policy. A task that never settles occupies a worker indefinitely, and the pool's overall promise keeps waiting. Cancellation must reach the underlying operation through a supported mechanism such as an AbortSignal. A wrapper that merely stops waiting is not proof that the underlying request has stopped consuming resources.
Our pool has no cancellation policy. If you add one, decide whether queued items are skipped, how in-flight tasks receive the signal, and how skipped work appears in the results. Test those decisions explicitly rather than treating any rejection as a universal stop command.
Concurrency is not a requests-per-second limit
A limit of three means at most three task calls are unsettled at a time. It does not mean three requests per second. With a hypothetical steady 100 ms task duration and immediate replacement, three occupied workers could complete roughly thirty tasks per second. Faster responses can therefore increase throughput while the concurrency setting stays unchanged.
A provider's time-window quota requires a separate pacing or token-budget policy. A limit applied inside one HTTP handler is also local to that invocation: ten simultaneous handlers can each create their own pool. Account-wide limits may need coordination across processes, replicas, and callers. Measure the scope where the provider actually enforces its quota.
Start with a conservative limit and observe active tasks, queue wait time, total task duration, errors, and upstream throttling. The HTTP status explorer can help interpret a response code, but choose retry behavior from the endpoint's documented contract.
Keep retries and memory inside the design
Retrying every failure immediately can recreate the burst you were trying to control. Keep a bounded retry budget and backoff policy, and decide whether backoff occupies a worker or returns the item to a separately managed queue. For operations that change state, apply the API retry and idempotency checklist before adding retries. A concurrency limit does not prevent duplicate business actions.
This sample keeps the entire input snapshot and every result in memory. It bounds active tasks, not total queue size or result size. For a large export or an unbounded stream, use a producer that observes backpressure and a result sink that can write incrementally. Avoid loading millions of rows simply because the request fan-out is now controlled.
A checklist for bounded fan-out
- Find the function call that starts each operation; do not enqueue already-started promises.
- State the limit's scope: one batch, one process, or a shared provider budget.
- Keep the complete task lifecycle inside the promise that occupies the worker.
- Preserve an input index or stable identifier for every success and failure.
- Test the peak active count, empty input, ordering, and both synchronous and asynchronous failures.
- Define timeout, cancellation, retry, and partial-result behavior separately.
- Check requests-per-second quotas independently of concurrent-task limits.
- Bound queued inputs and retained results when workloads grow beyond small batches.
The goal is a measurable resource policy. You should be able to state how much work can be active, which result belongs to which input, and what happens when a task fails or never finishes. A collection of promises alone cannot answer those questions.
Related Posts

Fetch Timeouts: Cancel Slow Requests and Response Bodies
Use AbortSignal to bound fetch and body reads, preserve caller cancellation, and test timeout behavior with a working local HTTP server.

Cursor Pagination: Stop Repeating Rows in a Changing Feed
Build stable cursor pagination with a runnable JavaScript example, timestamp tie-breakers, PostgreSQL queries, and a practical API checklist.

Large JSON IDs: Stop JavaScript From Rounding Database Keys
Keep large database IDs exact across JSON APIs with string contracts, boundary validation, and runnable JavaScript precision tests.