request-promise

Postconditions — what we check

• default · http-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and options.simple is true (default)
  ThrowsStatusCodeError with statusCode, error (response body), options, and response properties
  Required handlingCaller MUST catch StatusCodeError and check err.statusCode to handle HTTP errors. Default behavior (simple: true) throws on non-2xx status codes.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• default · network-failure

  error
  Whennetwork error, DNS failure, timeout, or connection refused
  ThrowsRequestError with cause (underlying error), error, options, and response properties
  Required handlingCaller MUST catch RequestError to handle network failures. Check err.cause for underlying error details (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, etc.).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][3]
• default · transform-function-error

  error
  Whenoptions.transform() function is configured and throws an error during execution
  ThrowsTransformError with cause (the error thrown by the transform function), error, options, and response properties. TransformError.name === 'TransformError'.
  Required handlingCallers using options.transform MUST also handle TransformError in addition to StatusCodeError and RequestError. A catch block catching only StatusCodeError will silently swallow transform failures, causing the promise to never settle. TransformError.cause contains the original error from the transform function.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[4][5][6]
• get · http-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and options.simple is true (default)
  ThrowsStatusCodeError with statusCode, error, options, and response properties
  Required handlingCaller MUST catch StatusCodeError when using rp.get(). Same behavior as calling rp() directly — non-2xx responses reject unless simple: false is set.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• get · network-failure

  error
  Whennetwork error, DNS failure, timeout, or connection refused
  ThrowsRequestError wrapping the underlying Node.js error
  Required handlingCaller MUST catch RequestError for network-level failures. Check err.cause for the underlying error (ECONNREFUSED, ENOTFOUND, etc.).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• post · http-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and options.simple is true (default)
  ThrowsStatusCodeError with statusCode, error, options, and response properties
  Required handlingCaller MUST catch StatusCodeError when using rp.post().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• post · network-failure

  error
  Whennetwork error, DNS failure, timeout, or connection refused
  ThrowsRequestError wrapping the underlying Node.js error
  Required handlingCaller MUST catch RequestError for network failures when using rp.post().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• put · http-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and options.simple is true (default)
  ThrowsStatusCodeError with statusCode, error, options, and response properties
  Required handlingCaller MUST catch StatusCodeError when using rp.put(). PUT requests to missing or unauthorized resources (404, 403) will reject by default.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][7]
• put · network-failure

  error
  Whennetwork error, DNS failure, timeout, or connection refused
  ThrowsRequestError wrapping the underlying Node.js error
  Required handlingCaller MUST catch RequestError for network failures when using rp.put().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• patch · http-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and options.simple is true (default)
  ThrowsStatusCodeError with statusCode, error, options, and response properties
  Required handlingCaller MUST catch StatusCodeError when using rp.patch(). PATCH requests to resources that don't exist (404) or where the user lacks permission (403) will reject by default.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][7]
• patch · network-failure

  error
  Whennetwork error, DNS failure, timeout, or connection refused
  ThrowsRequestError wrapping the underlying Node.js error
  Required handlingCaller MUST catch RequestError for network failures when using rp.patch().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• del · http-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and options.simple is true (default)
  ThrowsStatusCodeError with statusCode, error, options, and response properties
  Required handlingCaller MUST catch StatusCodeError when using rp.del() or rp.delete(). DELETE on a resource that doesn't exist (404) or lacks permission (403) will reject. A 404 on a repeated DELETE is common — check statusCode before retrying.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][7]
• del · network-failure

  error
  Whennetwork error, DNS failure, timeout, or connection refused
  ThrowsRequestError wrapping the underlying Node.js error
  Required handlingCaller MUST catch RequestError for network failures when using rp.del().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• head · http-error-4xx-5xx

  error
  Whenresponse status is 4xx or 5xx and options.simple is true (default)
  ThrowsStatusCodeError with statusCode, error, options, and response properties
  Required handlingCaller MUST catch StatusCodeError when using rp.head(). A 404 HEAD check for resource existence will reject by default — this is a common gotcha when using HEAD to probe whether a resource exists.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][7]
• head · network-failure

  error
  Whennetwork error, DNS failure, timeout, or connection refused
  ThrowsRequestError wrapping the underlying Node.js error
  Required handlingCaller MUST catch RequestError for network failures when using rp.head().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• head · head-resolves-with-headers-not-body

  warning
  Whenrequest succeeds (2xx)
  ReturnsResponse headers object (not body) by default, because HTTP HEAD responses have no body. Set resolveWithFullResponse: true to get the full response object instead.
  Required handlingCallers MUST NOT expect a body from rp.head(). The resolved value is the response.headers object by default. This differs from all other HTTP method shortcuts which resolve with the body.
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[8]

Sources

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

1. [1]github.com/request/request-promisehttps://github.com/request/request-promise
2. [2]github.com/request/request-promise-corehttps://github.com/request/request-promise-core/blob/master/lib/plumbing.js#L104
3. [3]github.com/request/request-promise-corehttps://github.com/request/request-promise-core/blob/master/lib/plumbing.js#L87
4. [4]github.com/request/request-promisehttps://github.com/request/request-promise#migration-from-v2-to-v3
5. [5]github.com/request/request-promise-corehttps://github.com/request/request-promise-core/blob/master/lib/plumbing.js#L100
6. [6]github.com/request/request-promise-corehttps://github.com/request/request-promise-core/blob/master/lib/errors.js
7. [7]github.com/DefinitelyTyped/DefinitelyTypedhttps://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/request/index.d.ts
8. [8]github.com/request/request-promise-corehttps://github.com/request/request-promise-core/blob/master/lib/plumbing.js#L62