Set request timeouts

Set a per-attempt limit and an overall limit when a request must not wait indefinitely.

When to use request timeouts

Use timeout to cap the time Ky spends waiting for a response on each attempt. Set totalTimeout when retries and their delays must also fit within one overall time budget. Ky is an HTTP client based on the Fetch API, so make the request with ky and pass these as request options.

Set both limits on a request

Pass both limits in the request options. When the response arrives and its body is read within the limits, .json() resolves with the parsed value and the sample logs it.

ts
import ky from 'ky';

async function loadReports(): Promise<void> {
	const reports = await ky.get('https://api.example.com/reports', {
		timeout: 5_000,
		totalTimeout: 30_000,
	}).json();

	console.log(reports);
}

void loadReports();

Timeout options

Option	Type	Default	What it does
`timeout`	`number \| false`	`10000`	Limits each attempt while waiting for a response. Ky's shortcut body methods, such as `.json()`, also use it as a separate limit for reading the response body. `false` disables the per-attempt limit.
`totalTimeout`	`number \| false`	`false`	Limits the whole operation, including retries and retry delays. If the limit is exceeded, Ky throws a `TimeoutError`. `false` or omitting the option disables this overall limit.
`retry.retryOnTimeout`	`boolean`	`false`	Enables retries when a timeout happens before Ky receives a response.

Both numeric timeout values must not exceed 2147483647 milliseconds. beforeError hooks run after Ky produces an error and are not bounded by totalTimeout.

Retry failed requests explains retry rules and retry timing.
Ky errors and validation covers Ky's error types and handling patterns.

When to use request timeouts

Set both limits on a request

Timeout options

Related

Was this page helpful?