Guide · Open source

How to use ky: install, make requests and handle errors

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Ky is a small JavaScript library for making HTTP requests, such as loading data from a web server or sending data to one. It wraps the browser's built-in fetch function and adds JSON handling, error handling for non-2xx status codes, retries, and timeouts. This guide shows you how to install it, make common requests, and handle errors, so you can write less boilerplate when calling a REST API.

kysindresorhus/ky · ★ 17.1k · MIT Install options & downloads

Quick start

1Install the package. Run npm install ky in your project folder. Make sure you have Node.js, or use a modern browser, Bun, or Deno.
2Import Ky. Add import ky from 'ky'; at the top of your file. In Deno, import it from a URL instead.
3Make a request. Call a method such as ky.get or ky.post, passing the URL. Use the json option to send an object as JSON.
4Read the response. Chain .json() to parse the body in the same call, or use .text() or another body method.
5Add types. Pass a type parameter to .json(), or validate the response with a Standard Schema validator such as Zod.
6Handle errors. Catch HTTPError for non-2xx responses and SchemaValidationError for failed validation.

What Ky is and when to use it

Ky is a tiny HTTP client based on the Fetch API. The project's README says it has no dependencies and targets modern browsers, Node.js, Bun, and Deno.

Ky is a code library, so it fits people writing JavaScript or TypeScript. It is a good match if you already use fetch and want less repetitive code around it.

Simpler API than plain fetch, with method shortcuts such as ky.post()
Treats non-2xx status codes as errors after redirects
Retries failed requests and supports timeouts
Accepts a JSON option for sending JSON bodies
Typed responses through TypeScript generics

Install Ky with npm

Install Ky with the package manager. The README gives this command for npm. Ky runs in modern browsers, Node.js, Bun, or Deno.

Requirement: Node.js or a modern browser, Bun, or Deno
In Deno, you can import Ky from a URL instead, for example from a CDN such as esm.sh

npm install ky

Make a request and read JSON

Import ky and call a method shortcut. Calling .json() on the result sends the request and parses the response body as JSON in one call, so you do not need to await the Response first.

Ky's JSON option stringifies an object for you and sets the Content-Type header to application/json unless you set your own Content-Type header.

import ky from 'ky';

const json = await ky.post('https://example.com', {json: {foo: true}}).json();

console.log(json);
//=> {data: '🦄'}

Fetch a resource with a relative URL

When you call Ky with a path, it sends a request to that path. The baseUrl option resolves relative input against a base URL, which is useful when you want several requests to share one host. The README recommends a trailing slash on a baseUrl that has a path.

Use baseUrl with ky.extend() to create instances tailored to one API
Absolute URLs bypass baseUrl

import ky from 'ky';

const user = await ky('/api/user').json();

console.log(user);

Add TypeScript types to responses

The .json() method accepts an optional type parameter. It defaults to unknown, not any, so you must declare a type to get typed data. You can pass the type with ky<User>() or with .json<User>().

You can also validate the JSON with a Standard Schema compatible validator such as Zod 3.24 or later. If validation fails, Ky throws a SchemaValidationError.

import ky, {SchemaValidationError} from 'ky';
import {z} from 'zod';

const userSchema = z.object({name: z.string()});

try {
	const user = await ky('/api/user').json(userSchema);
	console.log(user.name);
} catch (error) {
	if (error instanceof SchemaValidationError) {
		console.error(error.issues);
	}
}

Handle errors from non-2xx responses

Unlike the body methods of window.fetch, Ky's body shortcuts throw an HTTPError when the response status is outside 200 to 299. Ky does not throw for an invalid input or options in the same way; those reject the promise, the same way fetch reports them.

Note that .json() throws if the body is empty, because it cannot be parsed. The parseJson option lets you add custom handling for empty bodies.

Catch HTTPError to handle failed API calls in one place
Use parseJson to handle empty response bodies

Compare Ky with plain fetch

With plain fetch, you must set the method, stringify the body, set the header, check response.ok, and parse the JSON yourself. Ky's JSON option and body shortcuts handle those steps in one call.

The README's own example shows the plain fetch version of the same POST request, which is considerably longer.

What people use it for

Calling a REST API from a browser front end and parsing JSON responses
Sending a JSON payload to a server with ky.post() and the json option
Creating an API client instance with a baseUrl and shared defaults using ky.extend()
Uploading or downloading data with progress tracking, as listed in the README's feature list

Frequently asked questions

How do I install Ky?

Run npm install ky in your project. The README lists Node.js or a modern browser, Bun, or Deno as the prerequisites. In Deno, you can import Ky from a URL instead of installing it.

Is Ky free to use?

Ky is open source under the MIT licence, as listed on its repository page. You can check the LICENSE file in the repository for the full terms.

Does Ky have any dependencies?

The README says Ky is a tiny package with no dependencies. It builds on the Fetch API that is already built into browsers, Node.js, Bun, and Deno.

What is the difference between Ky and fetch?

Ky is built on fetch and adds conveniences such as JSON handling, method shortcuts, retries, timeouts, and errors for non-2xx status codes. Plain fetch does not throw for error status codes by default.

Why does .json() throw an error on an empty response?

The README says .json() throws when the body is empty because it cannot be parsed. You can use the parseJson option to add custom handling for empty bodies.

What are the alternatives to Ky?

Projects often compared with Ky include axios, got, ofetch, and node-fetch. Pick based on whether you want a Fetch-based library or a different API style, and on which runtimes you target.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Ky suits JavaScript or TypeScript developers who already use fetch and want JSON parsing, error handling, and typed responses with less code, especially in a small, dependency-free package. If you are not writing JavaScript, or you need a feature the README does not mention, such as a cookie jar, or you must support environments without fetch, pick a different HTTP client.

Install options & downloads