got

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]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/sindresorhus/gothttps://github.com/sindresorhus/got/blob/main/documentation/8-errors.md
2. [2]github.com/sindresorhus/gothttps://github.com/sindresorhus/got/blob/main/dist/source/core/response.d.ts
3. [3]github.com/sindresorhus/gothttps://github.com/sindresorhus/got/blob/main/dist/source/core/errors.d.ts
4. [4]github.com/sindresorhus/gothttps://github.com/sindresorhus/got/blob/main/documentation/3-streams.md
5. [5]github.com/sindresorhus/gothttps://github.com/sindresorhus/got/blob/main/documentation/4-pagination.md
6. [6]github.com/sindresorhus/gothttps://github.com/sindresorhus/got/blob/main/documentation/10-instances.md
7. [7]github.com/sindresorhus/gothttps://github.com/sindresorhus/got/blob/main/dist/source/as-promise/types.d.ts