Postman Request Client

Common errors

• Error: self signed certificate in certificate chain

  cause The server's SSL certificate is self-signed or not trusted by the client's CA store.
  fix Ensure your system's root CA certificates are up-to-date. For private/self-signed CAs, pass the certificate authority via the `ca` option in the request configuration. Avoid `strictSSL: false` for security.

• TypeError: request is not a function

  cause Incorrect import statement, often when trying to use ESM `import` syntax with a CommonJS module, or destructuring incorrectly.
  fix Use `const request = require('postman-request');` for CommonJS environments, which is the module's primary export pattern.

• Callback was already called.

  cause A callback function was invoked multiple times, usually due to an internal error handling path or a malformed server response triggering a secondary error after the initial callback.
  fix Ensure your callback function only handles a single invocation. While `postman-request` aims to fix common `request` issues, robust error handling with flags can prevent double invocation: `let called = false; if (!called) { called = true; /* ...handle response... */ }`

Warnings

• breaking Original 'request' module is abandoned; 'postman-request' is a fork with bug fixes. While largely compatible, subtle behavioral differences might affect existing code.
  Fix: Review existing `request` calls against `postman-request`'s specific bug fixes and added features. Test thoroughly to ensure compatibility, especially for edge cases in HTTP handling.
• gotcha Legacy API and CommonJS-first design. The underlying `request` API is considered legacy compared to `node-fetch` or `axios`.
  Fix: Prefer `require()` for consistency. If strict ESM is needed, investigate dynamic `import()` or build tool configurations. For new projects, consider modern Promise-based HTTP clients like `axios` or `node-fetch`.
• gotcha Stream error handling requires specific placement. When chaining streams, an `error` event listener must be attached *before* piping.
  Fix: Attach `.on('error', handler)` directly to the `request` call before any `.pipe()` operations to ensure proper error capture for upstream failures.
• gotcha Not a general-purpose HTTP client for new projects. While actively maintained by Postman, its primary purpose is internal Postman Runtime needs.
  Fix: For new application development not specifically tied to the original `request` API, modern HTTP clients (e.g., `node-fetch`, `axios`) offer more contemporary APIs and features.
• gotcha SSL/TLS certificate validation issues can occur. Misconfigured environments or self-signed certificates might lead to errors like 'self signed certificate'.
  Fix: Ensure environments have up-to-date root CA certificates. For custom CAs, use the `ca` option to provide trusted certificates. Avoid disabling SSL validation (`strictSSL: false` or `rejectUnauthorized: false`) in production due to security risks.

Install

• npm install postman-request npm
• yarn add postman-request yarn
• pnpm add postman-request pnpm

Imports

• request
  wrong:

  import request from 'postman-request';

  correct:

  const request = require('postman-request');

  Primarily designed for CommonJS; direct ESM import might require specific configuration or a build step, as shown in the quickstart and examples.
• request.post
  wrong:

  import { post } from 'postman-request';

  correct:

  const request = require('postman-request');
  request.post('http://example.com/upload', { form: { key: 'value' } }, (error, response, body) => { /* ... */ });

  Convenience methods like `post` are accessed directly from the main `request` object, not as named exports.
• request.defaults
  wrong:

  const defaultRequest = require('postman-request').defaults;

  correct:

  const request = require('postman-request');
  const defaultRequest = request.defaults({ headers: { 'User-Agent': 'my-app' } });

  `defaults` is a method on the `request` function, used to create a new `request` instance with pre-set options.

Quickstart

Demonstrates a basic GET request to Google, logging the error, status code, and response body length.

const request = require('postman-request');

request('http://www.google.com', function (error, response, body) {
  if (error) {
    console.error('Error:', error);
    return;
  }
  console.log('statusCode:', response && response.statusCode); // Print the response status code if a response was received
  console.log('body length:', body ? body.length : 0); // Print the length of the Google homepage HTML
});