superagent

Postconditions — what we check

• get · network-error-handling

  error
  Whennetwork failure, DNS error, timeout, connection refused, HTTP 4xx/5xx errors
  ThrowsError with status, response, timeout fields (Promise rejection)
  Required handlingUse try-catch (async/await) or .catch() (promises) or .end() callback
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• get · timeout-error-identifiable

  warning
  Whenrequest exceeds deadline (.timeout(ms)) or response timeout (.timeout({response:ms}))
  ThrowsError with err.timeout=<number> and err.code='ETIME' (deadline) or 'ETIMEDOUT' (response timeout)
  Required handlingCheck err.timeout in catch block to distinguish timeout from network errors; retry with backoff if appropriate
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• get · max-response-size-exceeded

  error
  Whenresponse body exceeds maxResponseSize limit (default 200MB for buffered responses)
  ThrowsError with code='ETOOLARGE' and message='Maximum response size reached'
  Required handlingHandle in catch block; check err.code === 'ETOOLARGE' for specific handling; use streaming .pipe() for large responses instead of buffering
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[3]
• post · network-error-handling

  error
  Whennetwork failure, DNS error, timeout, connection refused, HTTP 4xx/5xx errors
  ThrowsError with status, response, timeout fields (Promise rejection)
  Required handlingUse try-catch (async/await) or .catch() (promises) or .end() callback
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• post · timeout-error-identifiable

  warning
  Whenrequest exceeds deadline or response timeout
  ThrowsError with err.timeout=<number> and err.code='ETIME' (deadline) or 'ETIMEDOUT' (response timeout)
  Required handlingCheck err.timeout in catch to distinguish timeout from auth/rate-limit errors; POST requests are not idempotent so do not auto-retry without deduplication
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• put · network-error-handling

  error
  Whennetwork failure, DNS error, timeout, connection refused, HTTP 4xx/5xx errors
  ThrowsError with status, response, timeout fields (Promise rejection)
  Required handlingUse try-catch (async/await) or .catch() (promises) or .end() callback
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• patch · network-error-handling

  error
  Whennetwork failure, DNS error, timeout, connection refused, HTTP 4xx/5xx errors
  ThrowsError with status, response, timeout fields (Promise rejection)
  Required handlingUse try-catch (async/await) or .catch() (promises) or .end() callback
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• delete · network-error-handling

  error
  Whennetwork failure, DNS error, timeout, connection refused, HTTP 4xx/5xx errors
  ThrowsError with status, response, timeout fields (Promise rejection)
  Required handlingUse try-catch (async/await) or .catch() (promises) or .end() callback
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• del · network-error-handling

  error
  Whennetwork failure, DNS error, timeout, connection refused, HTTP 4xx/5xx errors
  ThrowsError with status, response, timeout fields (Promise rejection)
  Required handlingUse try-catch (async/await) or .catch() (promises) or .end() callback
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• head · network-error-handling

  error
  Whennetwork failure, DNS error, timeout, connection refused, HTTP 4xx/5xx errors
  ThrowsError with status, response, timeout fields (Promise rejection)
  Required handlingUse try-catch (async/await) or .catch() (promises) or .end() callback
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• pipe · pipe-errors-not-promise-rejections

  error
  WhenAny error during a piped request: network failure, DNS resolution error, connection refused, HTTP 4xx/5xx response, or timeout. Unlike awaited superagent calls, piped requests bypass the Promise chain entirely — .pipe() returns the destination stream immediately, not a Promise.
  ThrowsDoes NOT throw or reject a Promise. Errors are emitted as 'error' events: (1) Network/HTTP errors: emitted on the Request object via req.emit('error', err) where err.status is set for HTTP errors, absent for network/DNS errors. (2) Decompression errors (gzip/deflate responses): emitted on the destination stream via stream.emit('error', err). err.code='Z_BUF_ERROR' (truncated gzip) is silently swallowed by superagent; other zlib errors propagate to dest stream. If no 'error' listener is registered, Node.js throws an uncaught exception and may crash the process.
  Required handlingMUST register an 'error' event listener on the Request object before calling pipe(). Try-catch and async/await provide zero protection — errors bypass them silently, leaving the destination stream in an incomplete state with no indication of failure. Correct pattern: const req = superagent.get(url); req.on('error', handler); req.pipe(dest); Also register 'error' on the destination stream for decompression errors: dest.on('error', (err) => { /* handle decompression errors */ });
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[4][5]
• pipe · pipe-cannot-be-mixed-with-promise

  error
  WhenCalling .pipe() after .then()/.catch()/await on the same request, or attempting to pipe the Response object (res.pipe()) received in an .end() callback. Common mistake: const res = await superagent.get(url); res.pipe(stream) — pipe() belongs on the Request, not the Response, and await has already consumed the response via end().
  ThrowsSynchronous Error with message "end() has already been called, so it's too late to start piping" when pipe() is called on the Response object after end() has run. If pipe() is called on the Request after await (same request), behavior is undefined and data may be silently lost without any error.
  Required handlingUse EITHER streaming OR promise/callback — never both on the same request. Streaming: const req = superagent.get(url); req.on('error', h); req.pipe(stream); Promise: const res = await superagent.get(url); process(res.body); If a response must be both processed and streamed, buffer first then write manually.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4]
• agent · agent-request-network-error

  error
  Whennetwork failure, DNS error, connection refused, or HTTP 4xx/5xx on agent.get/post/put/patch/delete/head()
  ThrowsError with err.status (HTTP errors) or no err.status (network errors), plus err.response for HTTP errors
  Required handlingWrap agent HTTP method calls in try-catch; agent persists cookies so session errors (401, 403) may indicate expired auth that must be re-established
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[6]
• agent · agent-session-auth-failure

  error
  When401 Unauthorized or 403 Forbidden response when agent session/cookie has expired
  ThrowsError with err.status=401 or err.status=403 and err.response containing the response body
  Required handlingCatch 401/403 specifically and re-authenticate: check err.status === 401 to detect session expiry. Agents carry cookies across requests — a 401 mid-session means the cookie/token expired and must be refreshed before retrying. Do not silently swallow these errors or the agent will continue sending expired credentials.
  costmediumin prodimmediate exceptionusers seeauthentication failurevisibilitysilent
  Sources[6][5]

Sources

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

1. [1]forwardemail.github.io/superagenthttps://forwardemail.github.io/superagent/
2. [2]forwardemail.github.io/superagenthttps://forwardemail.github.io/superagent/#timeouts
3. [3]forwardemail.github.io/superagenthttps://forwardemail.github.io/superagent/#response-body
4. [4]forwardemail.github.io/superagenthttps://forwardemail.github.io/superagent/#piping
5. [5]forwardemail.github.io/superagenthttps://forwardemail.github.io/superagent/#error-handling
6. [6]forwardemail.github.io/superagenthttps://forwardemail.github.io/superagent/#agents-for-global-state