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.
tsimport 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.
Related
- Retry failed requests explains retry rules and retry timing.
- Ky errors and validation covers Ky's error types and handling patterns.
Was this page helpful?