Clarify docs for got.HTTPError

[chinesedfan]

Checklist

• I have read the documentation.
• I have included a pull request description of my changes.
• I have included some tests.
• If it's a new feature, I have included documentation updates.

Closed #1213. The preview is as following, and note that the anchor is a relative link so it doesn't work here but doesn't matter in fact.

---

Determines if a got.HTTPError is thrown for error responses.

got.ParseError

ok: 2xx or 304, and includes other 3xx if options.followRedirect is set

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

got.HTTPError

When the server response code is not ok. Includes a response property.

[szmarczak]

This actually does not affect ParseError.

[chinesedfan]

@szmarczak Not really. See source/as-promise/index.ts.

// Parse body
try {
    response.body = parseBody(response, options.responseType, options.encoding);
} catch (error) {
    // Fallback to `utf8`
    response.body = rawBody.toString();

    if (isOk()) {
        // TODO: Call `request._beforeError`, see https://github.com/nodejs/node/issues/32995
        reject(error);
        return;
    }
}

[szmarczak]

It doesn't have any effect. This code is not executed on redirects. 304 are empty responses, so even with responseType: 'json' it never throws:

got/source/as-promise/core.ts

Lines 28 to 30 in ece94ed

	if (responseType === 'json') {
	return rawBody.length === 0 ? '' : JSON.parse(rawBody.toString()) as unknown;
	}

There is no response event emitted on redirect:

got/source/core/index.ts

Lines 1032 to 1114 in ece94ed

	if (options.followRedirect && response.headers.location && redirectCodes.has(statusCode)) {
	// We're being redirected, we don't care about the response.
	// It'd be besto to abort the request, but we can't because
	// we would have to sacrifice the TCP connection. We don't want that.
	response.resume();
	if (this[kRequest]) {
	this[kCancelTimeouts]!();
	// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
	delete this[kRequest];
	this[kUnproxyEvents]();
	}
	const shouldBeGet = statusCode === 303 && options.method !== 'GET' && options.method !== 'HEAD';
	if (shouldBeGet || !options.methodRewriting) {
	// Server responded with "see other", indicating that the resource exists at another location,
	// and the client should request it from that location via GET or HEAD.
	options.method = 'GET';
	if ('body' in options) {
	delete options.body;
	}
	if ('json' in options) {
	delete options.json;
	}
	if ('form' in options) {
	delete options.form;
	}
	}
	if (this.redirects.length >= options.maxRedirects) {
	this._beforeError(new MaxRedirectsError(this));
	return;
	}
	try {
	// Handles invalid URLs. See https://github.com/sindresorhus/got/issues/604
	const redirectBuffer = Buffer.from(response.headers.location, 'binary').toString();
	const redirectUrl = new URL(redirectBuffer, url);
	const redirectString = redirectUrl.toString();
	decodeURI(redirectString);
	// Redirecting to a different site, clear sensitive data.
	if (redirectUrl.hostname !== url.hostname) {
	if ('host' in options.headers) {
	delete options.headers.host;
	}
	if ('cookie' in options.headers) {
	delete options.headers.cookie;
	}
	if ('authorization' in options.headers) {
	delete options.headers.authorization;
	}
	if (options.username || options.password) {
	delete options.username;
	delete options.password;
	}
	}
	this.redirects.push(redirectString);
	options.url = redirectUrl;
	for (const hook of options.hooks.beforeRedirect) {
	// eslint-disable-next-line no-await-in-loop
	await hook(options, typedResponse);
	}
	this.emit('redirect', typedResponse, options);
	await this._makeRequest();
	} catch (error) {
	this._beforeError(error);
	return;
	}
	return;
	}

[szmarczak]

You need to replace not ok with a more descriptive information.

[chinesedfan]

I want to make ok as a term, as well as used in ParseError.

[szmarczak]

Keep things simple. Don't redefine things. Simply:

When the server response code is not 2xx nor 3xx if options.followRedirect is true.

[szmarczak]

^^^

[szmarczak]

Looks good. Thanks for submitting! 🙌