Skip to content
Ky logo

Ky

OfficialBetav0.1.0

@kubb/plugin-ky

kubb add plugin-ky

Handle errors

Handle HTTP and network errors in the generated Ky client with ResponseError, or return errors as values with throwOnError: false.

What a call does

Only a non-2xx response depends on throwOnError:

What happensResult
2xx responseResolves with data.
Non-2xx responseThrows a ResponseError. With throwOnError: false, resolves with error and status.
A body fails its schema (validator on)Throws a ParseError.
Invalid JSON under a JSON media typeThrows a ParseError.
Network or DNS failureRejects with the NetworkError from Ky.
No response headers within timeoutRejects with the TimeoutError from Ky.
Aborted signalRejects with the signal's reason.

Every failure that rejects with an Error also reaches client.interceptors.error. An abort whose reason is not an Error, such as abort('canceled'), skips it.

Catch a ResponseError

Narrow with ResponseError.is(error) instead of instanceof, because each generated package bundles its own ResponseError class:

import { getPetById } from './gen/clients/getPetById'
import { ResponseError } from './gen/.kubb/client'

try {
  const { data } = await getPetById({ path: { petId: 1 } })
} catch (error) {
  if (ResponseError.is(error)) console.error(error.status, error.data) // 404, the parsed error body
}
class ResponseError extends Error {
  data: TError // the parsed error body
  status: number
  statusText: string
  contentType: string | undefined
  headers: Headers // such as error.headers.get('Retry-After')
  request: Request
  response: Response
}

The message leaves out the query string: GET https://api.example.com/pets/1 failed with status 404 Not Found. request and response keep the full URL, so redact them before you log the whole error.

The examples set integerType: 'number'. With the default bigint, an int64 id takes 1n.

Narrow a thrown error by status

isResponseError<Responses>(error) narrows a caught error to one operation's ResponseError. A check on status then narrows data. For range keys such as 4xx, see Status ranges:

import { isResponseError } from './gen/.kubb/client'
import type { GetPetByIdResponses } from './gen/types/GetPetById'

try {
  await getPetById({ path: { petId: 7 } })
} catch (error) {
  if (isResponseError<GetPetByIdResponses>(error) && error.status === 404) {
    console.error(error.data) // GetPetById404
  }
}
The type argument is not checked at runtime, so keep the try around one operation.

Return the error instead

With throwOnError: false, the call resolves for every status. data is set on success and error on failure, and a check on status narrows both:

const result = await getPetById({ path: { petId: 1 }, throwOnError: false })

if (result.error !== undefined) console.error(result.status, result.error)
else console.info(result.data)

See Empty error bodies and default responses.

Set the generated default

throwOnErrorDefault on the plugin sets what a call does when it leaves throwOnError out. client.setConfig({ throwOnError }) does not change it:

pluginKy({ throwOnErrorDefault: false })

const list = await searchPets({ query: { status: 'available' } }) // resolves with an error result
const pet = await getPetById({ path: { petId: 1 }, throwOnError: true }) // throws

Validation failures

With validator on, a body that does not match its Zod schema throws a ParseError with the schema's issues:

import { ParseError } from './gen/.kubb/standardSchema'

try {
  await getPetById({ path: { petId: 1 } })
} catch (error) {
  if (error instanceof ParseError) console.error(error.issues) // [{ message, path }]
}

To recover, pass onValidationError on the call or the client. Return { value } to use that value, or nothing to throw the ParseError:

client.setConfig({
  onValidationError: (error, { direction, source, value }) => {
    console.warn(direction, source, error.issues)
    return { value }
  },
})

For which schema checks an error body, see Error body validation.

Turn validation off at runtime

validator decides at generation time which schemas a call carries. validate skips them at runtime, for example in production or in tests with partial fixtures:

client.setConfig({ validate: import.meta.env.DEV })
client.setConfig({ validate: { response: false } }) // skip one direction

The default is true. The object form skips each direction set to false: request (the body), params, response, or error. A per-call validate overrides the client.

Less common cases

Status ranges

When an operation declares a range key such as 4xx, the range covers its statuses that have no entry of their own, and default covers the rest.

Empty error bodies and default responses

When a failed call has an empty body, error is { status, statusText }.

When the operation declares a default response, a check on status does not narrow data and error, because a default status can be any number. To get the success body with the default returnType: 'full', call .unwrap(), which turns error into a rejection. With returnType: 'data', the call returns a plain promise without .unwrap().

Where the throwOnError default comes from

When you set client.setConfig({ throwOnError }), generated calls ignore it, because each generated function passes its own value: the call's throwOnError, or else throwOnErrorDefault. That value is also the default of the function's ThrowOnError type parameter.

Read headers with returnType: 'data'

When the plugin sets returnType: 'data', a call resolves to the success body alone. To read a header such as ETag, pass throwOnError: false and call result.headers.get('etag'). For a stream call, see Event IDs when you resume.

The query plugins and @kubb/plugin-mcp read returnType too, including a per-operation value from override.