Errors & security

OpenFetchError

Subclass of Error with optional:

• code — Machine-readable string
• config — Merged request config (may contain secrets)
• response — Present for failed validateStatus (ERR_BAD_RESPONSE)
• request — { url } when available

Codes (common)

Code	Meaning
ERR_BAD_RESPONSE	HTTP status failed validateStatus
ERR_NETWORK	Network / unexpected throw from fetch
ERR_PARSE	Response body could not be parsed
ERR_CANCELED	Aborted (typically external signal or user abort)
ERR_TIMEOUT	Per-request timeout elapsed (internal timer aborted fetch before user signal)
ERR_RETRY_TIMEOUT	Total retry budget (retry.timeoutTotalMs) exceeded (monotonic clock)

isOpenFetchError

Type guard: err is OpenFetchError.

isHTTPError / isTimeoutError

• isHTTPError(err) — OpenFetchError with code === "ERR_BAD_RESPONSE" and a response attached.
• isTimeoutError(err) — OpenFetchError with ERR_TIMEOUT (per-attempt fetch timeout) or ERR_RETRY_TIMEOUT (whole retry sequence budget).

SchemaValidationError / isSchemaValidationError

Thrown when jsonSchema or fluent .json(schema) validation fails. Not an OpenFetchError (the HTTP round-trip succeeded; the schema rejected the body). Use isSchemaValidationError for narrowing.

Logging — toShape() / toJSON()

toShape() returns a plain object: message, status, url, method, optional data / headers, code.

• config.auth is omitted from the shape, but the live error instance may still hold full config — do not send it raw to clients.
• For shared or client-facing logs, prefer:

error.toShape({
  includeResponseData: false,
  includeResponseHeaders: false,
});

Default toShape() / toJSON() includes response data and headers (backward compatible).

assertSafeHttpUrl(url)

Optional server-side guard when the URL may be influenced by untrusted input.

• Allows only http: / https:.
• Rejects localhost and literal private / loopback / link-local IPv4 and common IPv6 cases.
• Does not stop DNS rebinding (hostname resolving to internal IPs). Combine with hostname allowlists, egress controls, or proxies as needed.

Throws Error with messages prefixed openfetch: assertSafeHttpUrl:.

Header redaction for custom logs

When you build your own log lines (outside the debug plugin), use maskHeaderValues from the main package with MaskHeaderStrategy partial or hash — same strategies as debug({ maskStrategy, … }). See Configuration for the export table.

cloneResponse

If you hold a native Response (for example from rawResponse or .raw()) and need to read the body twice, use cloneResponse(res) from the package (or res.clone() on the Response).

Memory cache and auth

See Retry & cache: use varyHeaderNames or a custom key for per-user GETs.

Further reading

• Package SECURITY.md and npm run test:security (security test harness in the repo).