Postconditions: what we check

• default · http-error

  error
  WhenServer responds with a non-2xx, non-3xx status code and throwHttpErrors is true (default).
  ThrowsHTTPError with code ERR_NON_2XX_3XX_RESPONSE; error.response contains the full response
  Required handlingCaller MUST wrap in try-catch (async/await) or .catch() (promise chain). Inspect error.response.statusCode to distinguish client vs server errors. Do not retry 4xx errors without user intervention (except 408, 413, 429).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• default · network-error

  error
  WhenNetwork-level failure: DNS resolution failure (ENOTFOUND, EAI_AGAIN), connection refused (ECONNREFUSED), connection reset (ECONNRESET), timeout (ETIMEDOUT), no route (ENETUNREACH), or pipe broken (EPIPE). This is thrown after all retries are exhausted.
  ThrowsRequestError with a POSIX error code (e.g. ECONNREFUSED, ETIMEDOUT, ENOTFOUND)
  Required handlingCaller MUST wrap in try-catch. Check error.code for specific network condition. Got retries these automatically (limit=2 by default) before throwing — the thrown error is from the final attempt. Implement additional retry logic only if default retry is disabled.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• default · timeout-error

  error
  WhenOne of the timeout limits (connect, send, response, request, etc.) was exceeded.
  ThrowsTimeoutError (subclass of RequestError) with error.event indicating which phase timed out (e.g. 'connect', 'request', 'response'). Code is ETIMEDOUT.
  Required handlingCaller MUST wrap in try-catch. Check error.event to understand which phase timed out. ETIMEDOUT is in the default retry error codes — Got will retry before throwing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• default · max-redirects-error

  error
  WhenThe server redirected more than maxRedirects times (default: 10).
  ThrowsMaxRedirectsError (subclass of RequestError) with code ERR_TOO_MANY_REDIRECTS
  Required handlingCaller MUST wrap in try-catch. This indicates a redirect loop or misconfigured server. Do not retry automatically.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• default · parse-error

  error
  WhenServer responds with a 2xx status code, responseType is 'json' (or .json() shortcut is called), and the response body cannot be parsed as JSON. Also triggered when responseType is set to an unknown value. ParseError extends RequestError and includes a .response property with the raw body available at response.rawBody.
  ThrowsParseError with code ERR_BODY_PARSE_FAILURE. Declared in core/response.d.ts. error.response.rawBody contains the raw Uint8Array. error.message includes the JSON parse error message and the request URL.
  Required handlingCaller MUST wrap in try-catch. Distinguish from HTTPError by checking error instanceof got.ParseError (or error.code === 'ERR_BODY_PARSE_FAILURE'). This error means the HTTP request succeeded (2xx) but the body was not valid JSON. The raw body is accessible via error.response.rawBody for debugging. ParseError is NOT retried automatically (it's a successful HTTP response with bad content).
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[1][2]
• default · abort-error

  warning
  WhenAn AbortController's .abort() method is called while the request is in-flight. The AbortController signal is passed via options.signal.
  ThrowsAbortError (subclass of RequestError) with code ERR_ABORTED. This is a Promise rejection, not an event emission.
  Required handlingCaller MUST wrap in try-catch. Check error.code === 'ERR_ABORTED' or error instanceof got.AbortError. This is commonly used for request cancellation in UI components or when switching users/sessions. Note: AbortError is NOT automatically retried.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[1][3]
• get · http-error

  error
  WhenServer responds with non-2xx/3xx status and throwHttpErrors is true (default).
  ThrowsHTTPError with error.response containing status code and body
  Required handlingCaller MUST wrap in try-catch or .catch(). Check error.response.statusCode.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• get · network-error

  error
  WhenDNS failure, connection refused, connection reset, timeout, or unreachable network (after retries).
  ThrowsRequestError (or subclass TimeoutError) with a POSIX error code
  Required handlingCaller MUST wrap in try-catch. GET is in the default retry methods list — got will retry up to 2 times before throwing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• post · http-error

  error
  WhenServer responds with non-2xx/3xx status and throwHttpErrors is true (default).
  ThrowsHTTPError with error.response containing status code and body
  Required handlingCaller MUST wrap in try-catch or .catch(). Check error.response.statusCode.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• post · network-error

  error
  WhenDNS failure, connection refused, connection reset, timeout, or unreachable network.
  ThrowsRequestError or TimeoutError with POSIX error code
  Required handlingCaller MUST wrap in try-catch. NOTE: POST is NOT in got's default retry methods list, so the error is thrown after the first failure with no automatic retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• post · upload-error

  error
  WhenThe request body is a stream and an error occurs reading from that stream.
  ThrowsUploadError (subclass of RequestError)
  Required handlingCaller MUST wrap in try-catch. Validate body stream before sending.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• put · http-error

  error
  WhenServer responds with non-2xx/3xx status and throwHttpErrors is true (default).
  ThrowsHTTPError with error.response containing status code and body
  Required handlingCaller MUST wrap in try-catch or .catch(). Check error.response.statusCode.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• put · network-error

  error
  WhenDNS failure, connection refused, connection reset, timeout, or unreachable network (after retries).
  ThrowsRequestError or TimeoutError with POSIX error code
  Required handlingCaller MUST wrap in try-catch. PUT is in the default retry methods list — got will retry up to 2 times before throwing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• patch · http-error

  error
  WhenServer responds with non-2xx/3xx status and throwHttpErrors is true (default).
  ThrowsHTTPError with error.response containing status code and body
  Required handlingCaller MUST wrap in try-catch or .catch(). Check error.response.statusCode.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• patch · network-error

  error
  WhenDNS failure, connection refused, connection reset, timeout, or unreachable network.
  ThrowsRequestError or TimeoutError with POSIX error code
  Required handlingCaller MUST wrap in try-catch. NOTE: PATCH is NOT in got's default retry methods list, so the error is thrown after the first failure with no automatic retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• delete · http-error

  error
  WhenServer responds with non-2xx/3xx status and throwHttpErrors is true (default).
  ThrowsHTTPError with error.response containing status code and body
  Required handlingCaller MUST wrap in try-catch or .catch(). Check error.response.statusCode.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• delete · network-error

  error
  WhenDNS failure, connection refused, connection reset, timeout, or unreachable network (after retries).
  ThrowsRequestError or TimeoutError with POSIX error code
  Required handlingCaller MUST wrap in try-catch. DELETE is in the default retry methods list — got will retry up to 2 times before throwing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• head · http-error

  error
  WhenServer responds with non-2xx/3xx status and throwHttpErrors is true (default).
  ThrowsHTTPError with code ERR_NON_2XX_3XX_RESPONSE
  Required handlingCaller MUST wrap in try-catch or .catch().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• head · network-error

  error
  WhenDNS failure, connection refused, timeout, or unreachable network (after retries).
  ThrowsRequestError or TimeoutError with POSIX error code
  Required handlingCaller MUST wrap in try-catch. HEAD is in the default retry methods list.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• stream · stream-error-event

  error
  WhenAny error occurs during the request: network failure, timeout, HTTP error (when throwHttpErrors is true), read error, or upload error.
  ThrowsRequestError or subclass is emitted as an 'error' event on the stream. This is NOT a Promise rejection. Without an error listener, Node.js will throw an uncaught exception and crash the process.
  Required handlingCaller MUST attach an 'error' event listener: stream.on('error', handler). Using try-catch around got.stream() does NOT catch these errors. When piping, the error listener must be on the got stream itself, not just the destination stream.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][1]
• paginate · paginate-http-error

  error
  WhenAny paginated request receives a non-2xx/3xx response and throwHttpErrors is true (default).
  ThrowsHTTPError from the failing request; iteration stops immediately
  Required handlingCaller MUST wrap the for-await-of loop in try-catch. got.paginate.all() returns a Promise and must be wrapped in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• paginate · paginate-network-error

  error
  WhenAny paginated request fails with a network error (after retries).
  ThrowsRequestError or subclass; iteration stops immediately
  Required handlingCaller MUST wrap the for-await-of loop (or got.paginate.all() await) in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• extend · inherited-http-error

  error
  WhenAny request on the extended instance receives a non-2xx/3xx response and throwHttpErrors is true (default, unless overridden in extend options).
  ThrowsHTTPError — same as base got
  Required handlingCaller MUST wrap in try-catch or .catch(). Extended instances inherit all retry and error-throwing behavior from their parent. Check error.response.statusCode.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][1]
• extend · inherited-network-error

  error
  WhenAny request on the extended instance fails with a network error (after retries).
  ThrowsRequestError or subclass — same as base got
  Required handlingCaller MUST wrap in try-catch. Error behavior is identical to base got.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• json · json-parse-error

  error
  WhenThe HTTP request succeeds with a 2xx status code but the response body is not valid JSON (malformed, truncated, or empty). Common when an upstream service returns HTML error pages (e.g., a proxy 502 with HTML body) with a 2xx status, or when the Content-Type is wrong.
  ThrowsParseError with code ERR_BODY_PARSE_FAILURE. Declared in core/response.d.ts, exported from index.d.ts. error.response.rawBody contains the raw Uint8Array. error.message includes the JSON parse error and request URL.
  Required handlingCaller MUST wrap in try-catch. This is NOT the same as HTTPError (which means non-2xx response). ParseError means the HTTP handshake succeeded but data is unusable. Access error.response.rawBody for debugging. Check error.code === 'ERR_BODY_PARSE_FAILURE' or error instanceof ParseError to distinguish from network/HTTP errors. ParseError is NOT retried automatically.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[1][7]
• json · json-http-error

  error
  WhenServer responds with a non-2xx/3xx status code and throwHttpErrors is true (default). This propagates from the underlying got() call.
  ThrowsHTTPError with code ERR_NON_2XX_3XX_RESPONSE
  Required handlingCaller MUST wrap in try-catch. Same as the underlying got() call behavior.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• buffer · buffer-http-error

  error
  WhenServer responds with a non-2xx/3xx status code and throwHttpErrors is true (default).
  ThrowsHTTPError with code ERR_NON_2XX_3XX_RESPONSE
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• buffer · buffer-network-error

  error
  WhenNetwork failure during the request (after retries exhausted).
  ThrowsRequestError or subclass (TimeoutError, etc.)
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• text · text-http-error

  error
  WhenServer responds with a non-2xx/3xx status code and throwHttpErrors is true (default).
  ThrowsHTTPError with code ERR_NON_2XX_3XX_RESPONSE
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• text · text-network-error

  error
  WhenNetwork failure during the request (after retries exhausted).
  ThrowsRequestError or subclass (TimeoutError, etc.)
  Required handlingCaller MUST wrap in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• paginate.all · paginate-all-http-error

  error
  WhenAny paginated request receives a non-2xx/3xx response and throwHttpErrors is true (default). Iteration halts immediately and the Promise rejects \u2014 already-collected pages are NOT returned to the caller.
  ThrowsHTTPError from the failing request, propagated through Array.fromAsync
  Required handlingCaller MUST wrap `await got.paginate.all(...)` in try-catch or attach .catch(). On rejection, treat the entire result set as missing (no partial array is exposed). Inspect error.response.statusCode to distinguish client vs server failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1][8]
• paginate.all · paginate-all-network-error

  error
  WhenAny paginated request fails with a network error (DNS, ECONNREFUSED, ECONNRESET, timeout, etc.) after the configured retry budget is exhausted. Iteration halts and the Promise rejects with the final error.
  ThrowsRequestError or subclass (TimeoutError, ReadError, etc.) propagated through Array.fromAsync
  Required handlingCaller MUST wrap `await got.paginate.all(...)` in try-catch. The Promise rejects exactly once per call site \u2014 there is no per-page error callback. Discard the entire result set on rejection.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• stream.get · stream-alias-error-event

  error
  WhenAny error occurs during the request: network failure, timeout, HTTP error (when throwHttpErrors is true, default), read error, or upload error. The returned Duplex stream emits the error as an 'error' event \u2014 it does NOT reject any Promise (the shortcut does not return one).
  ThrowsRequestError (or subclass \u2014 HTTPError, TimeoutError, ReadError, UploadError) emitted as the argument to an 'error' event listener attached to the returned stream. Without an error listener, Node.js raises 'Uncaught Error' and crashes the process.
  Required handlingCaller MUST attach an 'error' event listener directly to the stream returned from got.stream.<method>() \u2014 stream.on('error', handler) or stream.once('error', handler). Using try-catch around got.stream.get(url) catches NOTHING because the shortcut returns synchronously before any I/O happens. When piping to a destination, use Node's stream.pipeline() (or attach the error listener on the got stream itself, not just the destination \u2014 the destination's 'error' event fires only for its own write errors, not upstream request errors).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][1][8]
• stream.post · stream-alias-error-event

  error
  WhenAny error during the request (network, timeout, HTTPError when throwHttpErrors=true, ReadError, UploadError on a body stream). Emitted as an 'error' event on the returned Duplex stream.
  ThrowsRequestError or subclass \u2014 emitted on stream 'error' event, NOT a Promise rejection.
  Required handlingCaller MUST attach stream.on('error', handler). try-catch around the got.stream.post() call itself catches nothing. When piping a request body in, attach the listener on the got stream before piping; use stream.pipeline() for the full pipe chain.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][8]
• stream.put · stream-alias-error-event

  error
  WhenAny error during the request (network, timeout, HTTPError when throwHttpErrors=true, ReadError, UploadError). Emitted on the stream's 'error' event.
  ThrowsRequestError or subclass \u2014 emitted on stream 'error' event, NOT a Promise rejection.
  Required handlingCaller MUST attach stream.on('error', handler). try-catch on the synchronous call site catches nothing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][8]
• stream.patch · stream-alias-error-event

  error
  WhenAny error during the request (network, timeout, HTTPError when throwHttpErrors=true, ReadError, UploadError). Emitted on the stream's 'error' event.
  ThrowsRequestError or subclass \u2014 emitted on stream 'error' event, NOT a Promise rejection.
  Required handlingCaller MUST attach stream.on('error', handler). try-catch on the synchronous call site catches nothing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][8]
• stream.head · stream-alias-error-event

  error
  WhenAny error during the request (network, timeout, HTTPError when throwHttpErrors=true, ReadError). Emitted on the stream's 'error' event.
  ThrowsRequestError or subclass \u2014 emitted on stream 'error' event, NOT a Promise rejection.
  Required handlingCaller MUST attach stream.on('error', handler). try-catch on the synchronous call site catches nothing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][8]
• stream.delete · stream-alias-error-event

  error
  WhenAny error during the request (network, timeout, HTTPError when throwHttpErrors=true, ReadError, UploadError). Emitted on the stream's 'error' event.
  ThrowsRequestError or subclass \u2014 emitted on stream 'error' event, NOT a Promise rejection.
  Required handlingCaller MUST attach stream.on('error', handler). try-catch on the synchronous call site catches nothing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][8]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

retry: {
  limit: 2,
  methods: ['GET', 'PUT', 'HEAD', 'DELETE', 'OPTIONS', 'TRACE'],
  // NOTE: POST and PATCH are NOT retried by default
  statusCodes: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
  errorCodes: ['ETIMEDOUT', 'ECONNRESET', 'EADDRINUSE', 'ECONNREFUSED',
               'EPIPE', 'ENOTFOUND', 'ENETUNREACH', 'EAI_AGAIN'],
  backoffLimit: Infinity,
  noise: 100  // ms of jitter
}

// CORRECT
const stream = got.stream('https://example.com');
stream.on('error', (error) => { ... });

// WRONG — try-catch does not work for stream errors
try {
  const stream = got.stream('https://example.com');
} catch (error) {
  // This will NOT catch stream errors
}