8-errors.md

> Back to homepage

Errors

Source code:

• source/core/errors.ts
• source/as-promise/types.ts
• source/core/response.ts

All Got errors contain various metadata, such as:

• code - A string like ERR_NON_2XX_3XX_RESPONSE,
• options - An instance of Options,
• request - An instance of Got Stream,
• response (optional) - An instance of Got Response,
• timings (optional) - Points to response.timings.

Note

SchemaValidationError is the exception: it comes from the user-provided schema instead of the request lifecycle, so the only metadata it adds is the schema issues.

Capturing async stack traces

Read the article here.

Note

• The error codes may differ when the root error has a code property set.
• The root error will be propagated as is via the cause property.

RequestError

Code: ERR_GOT_REQUEST_ERROR

When a request fails. Contains a code property with error class code, like ECONNREFUSED. All the errors below inherit this one, except SchemaValidationError.

CacheError

Code: ERR_CACHE_ACCESS

When a cache method fails, for example, if the database goes down or there's a filesystem error.

ReadError

Code: ERR_READING_RESPONSE_STREAM or ERR_HTTP_CONTENT_LENGTH_MISMATCH

When reading from response stream fails.

The error code will be ERR_HTTP_CONTENT_LENGTH_MISMATCH when the strictContentLength option is enabled and the server specifies a content-length header but the actual number of bytes received doesn't match.

ParseError

Code: ERR_BODY_PARSE_FAILURE

When server response code is 2xx, and parsing body fails. Includes a response property.

SchemaValidationError

When the response body does not match the Standard Schema validator passed to promise.json(schema). Includes an issues property with the issues from the schema. Each issue has a message and an optional path.

It intentionally does not extend RequestError, because the request succeeded. The user-provided schema did not accept the data, so it has no code, options, request, response or timings property, and it is not passed to beforeError hooks.

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

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

try {
	const user = await got('https://example.com/user').json(userSchema);
	console.log(user.name);
} catch (error) {
	if (error instanceof SchemaValidationError) {
		console.error(error.issues);
	} else {
		throw error;
	}
}

UploadError

Code: ERR_UPLOAD

When the request body is a stream and an error occurs while reading from that stream.

HTTPError

Code: ERR_NON_2XX_3XX_RESPONSE

When the request is unsuccessful.

A request is successful when the status code of the final request is 2xx or 3xx.

When following redirects, a request is successful only when the status code of the final request is 2xx.

Note

304 responses are always considered successful.

MaxRedirectsError

Code: ERR_TOO_MANY_REDIRECTS

When the server redirects you more than ten times. Includes a response property.

UnsupportedProtocolError

Note

This error is not public.

Code: ERR_UNSUPPORTED_PROTOCOL

When given an unsupported protocol.

TimeoutError

Code: ETIMEDOUT

When the request is aborted due to a timeout. Includes an event (a string) property along with timings.

RetryError

Code: ERR_RETRYING

Always triggers a new retry when thrown.

AbortError

Code: ERR_ABORTED

When the request is aborted with AbortController.abort().