options in socket.connect() are also supported.

The default http.globalAgent that is used by http.request() has all of these values set to their respective defaults.

To configure any of them, a custom http.Agent instance must be created.

import { Agent, request } from 'node:http';
const keepAliveAgent = new Agent({ keepAlive: true });
options.agent = keepAliveAgent;
request(options, onResponseCallback);const http = require('node:http');
const keepAliveAgent = new http.Agent({ keepAlive: true });
options.agent = keepAliveAgent;
http.request(options, onResponseCallback);copy

agent.createConnection(options[, callback]) #

Produces a socket/stream to be used for HTTP requests.

By default, this function is the same as net.createConnection() . However, custom agents may override this method in case greater flexibility is desired.

A socket/stream can be supplied in one of two ways: by returning the socket/stream from this function, or by passing the socket/stream to callback .

This method is guaranteed to return an instance of the <net.Socket> class, a subclass of <stream.Duplex> , unless the user specifies a socket type other than <net.Socket> .

callback has a signature of (err, stream) .

agent.keepSocketAlive(socket) #

Called when socket is detached from a request and could be persisted by the Agent . Default behavior is to:

socket.setKeepAlive(true, this.keepAliveMsecs);
socket.unref();
return true; copy

This method can be overridden by a particular Agent subclass. If this method returns a falsy value, the socket will be destroyed instead of persisting it for use with the next request.

The socket argument can be an instance of <net.Socket> , a subclass of <stream.Duplex> .

agent.reuseSocket(socket, request) #

Called when socket is attached to request after being persisted because of the keep-alive options. Default behavior is to:

socket.ref(); copy

This method can be overridden by a particular Agent subclass.

The socket argument can be an instance of <net.Socket> , a subclass of <stream.Duplex> .

agent.destroy() #

agent.freeSockets #

The request.aborted property will be true if the request has been aborted.

request.connection #

See request.socket .

request.cork() #

See writable.cork() .

request.end([data[, encoding]][, callback]) #

request.setHeader('content-type', 'text/html');
request.setHeader('Content-Length', Buffer.byteLength(body));
request.setHeader('Cookie', ['type=ninja', 'language=javascript']);
const contentType = request.getHeader('Content-Type');
// 'contentType' is 'text/html'
const contentLength = request.getHeader('Content-Length');
// 'contentLength' is of type number
const cookie = request.getHeader('Cookie');
// 'cookie' is of type string[] copy

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);
const headerNames = request.getHeaderNames();
// headerNames === ['foo', 'cookie'] copy

request.setHeader('Foo', 'bar');
request.setHeader('Cookie', ['foo=bar', 'bar=baz']);
const headers = request.getHeaders();
// headers === { foo: 'bar', 'cookie': ['foo=bar', 'bar=baz'] } copy

request.setHeader('Foo', 'bar');
request.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);
const headerNames = request.getRawHeaderNames();
// headerNames === ['Foo', 'Set-Cookie'] copy

const hasContentType = request.hasHeader('content-type'); copy

request.removeHeader('Content-Type'); copy

import http from 'node:http';
// Server has a 5 seconds keep-alive timeout by default
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  .listen(3000);
setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data'




    
, (data) => {
      // Do nothing
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeoutconst http = require('node:http');
// Server has a 5 seconds keep-alive timeout by default
  .createServer((req, res) => {
    res.write('hello\n');
    res.end();
  .listen(3000);
setInterval(() => {
  // Adapting a keep-alive agent
  http.get('http://localhost:3000', { agent }, (res) => {
    res.on('data', (data) => {
      // Do nothing
}, 5000); // Sending request on 5s interval so it's easy to hit idle timeoutcopy

import http from 'node:http';
const agent = new http.Agent({ keepAlive: true });
function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    .on('error', (err) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
retriableRequest();const http = require('node:http');
const agent = new http.Agent({ keepAlive: true });
function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    .on('error', (err) => {
      // Check if retry is needed
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
retriableRequest();copy

request.setHeader('Content-Type', 'application/json'); copy

request.setHeader('Cookie', ['type=ninja', 'language=javascript']); copy

const filename = 'Rock 🎵.txt';
request.setHeader('Content-Disposition', `attachment; filename*=utf-8''${encodeURIComponent(filename)}`); copy

import http from 'node:http';
const options = {
  host: 'www.google.com',
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});const http = require('node:http');
const options = {
  host: 'www.google.com',
const req = http.get(options);
req.end();
req.once('response', (res) => {
  const ip = req.socket.localAddress;
  const port = req.socket.localPort;
  console.log(`Your IP address is ${ip} and your source port is ${port}.`);
  // Consume response object
});copy

If a client connection emits an 'error' event, it will be forwarded here. Listener of this event is responsible for closing/destroying the underlying socket. For example, one may wish to more gracefully close the socket with a custom HTTP response instead of abruptly severing the connection. The socket must be closed or destroyed before the listener ends.

This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex> , unless the user specifies a socket type other than <net.Socket> .

Default behavior is to try close the socket with a HTTP '400 Bad Request', or a HTTP '431 Request Header Fields Too Large' in the case of a HPE_HEADER_OVERFLOW error. If the socket is not writable or headers of the current attached http.ServerResponse has been sent, it is immediately destroyed.

socket is the net.Socket object that the error originated from.

import http from 'node:http';
const server = http.createServer((req, res) => {
  res.end();
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
server.listen(8000);const http = require('node:http');
const server = http.createServer((req, res) => {
  res.end();
server.on('clientError', (err, socket) => {
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
server.listen(8000);copy

When the 'clientError' event occurs, there is no request or response object, so any HTTP response sent, including response headers and payload, must be written directly to the socket object. Care must be taken to ensure the response is a properly formatted HTTP response message.

err is an instance of Error with two extra columns:

In some cases, the client has already received the response and/or the socket has already been destroyed, like in case of ECONNRESET errors. Before trying to send data to the socket, it is better to check that it is still writable.

server.on('clientError', (err, socket) => {
  if (err.code === 'ECONNRESET' || !socket.writable) {
    return;
  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
}); copy

Event: 'close' #

Event: 'connect' #

Emitted each time a client requests an HTTP CONNECT method. If this event is not listened for, then clients requesting a CONNECT method will have their connections closed.

This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex> , unless the user specifies a socket type other than <net.Socket> .

After this event is emitted, the request's socket will not have a 'data' event listener, meaning it will need to be bound in order to handle data sent to the server on that socket.

Event: 'connection' #

This event is emitted when a new TCP stream is established. socket is typically an object of type net.Socket . Usually users will not want to access this event. In particular, the socket will not emit 'readable' events because of how the protocol parser attaches to the socket. The socket can also be accessed at request.socket .

This event can also be explicitly emitted by users to inject connections into the HTTP server. In that case, any Duplex stream can be passed.

If socket.setTimeout() is called here, the timeout will be replaced with server.keepAliveTimeout when the socket has served a request (if server.keepAliveTimeout is non-zero).

This event is guaranteed to be passed an instance of the <net.Socket> class, a subclass of <stream.Duplex> , unless the user specifies a socket type other than <net.Socket> .

Event: 'dropRequest' #

When the number of requests on a socket reaches the threshold of server.maxRequestsPerSocket , the server will drop new requests and emit 'dropRequest' event instead, then send 503 to client.

Event: 'request' #

Emitted each time there is a request. There may be multiple requests per connection (in the case of HTTP Keep-Alive connections).

Event: 'upgrade' #

If data is specified, it is similar in effect to calling response.write(data, encoding) followed by response.end(callback) .

If callback is specified, it will be called when the response stream is finished.

response.finished #

The response.finished property will be true if response.end() has been called.

response.flushHeaders() #

Flushes the response headers. See also: request.flushHeaders() .

response.getHeader(name) #

Reads out a header that's already been queued but not sent to the client. The name is case-insensitive. The type of the return value depends on the arguments provided to response.setHeader() .

response.setHeader('Content-Type', 'text/html');
response.setHeader('Content-Length', Buffer.byteLength(body));
response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
const contentType = response.getHeader('content-type');
// contentType is 'text/html'
const contentLength = response.getHeader('Content-Length');
// contentLength is of type number
const setCookie = response.getHeader('set-cookie');
// setCookie is of type string[] copy

response.getHeaderNames() #

Returns an array containing the unique names of the current outgoing headers. All header names are lowercase.

response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);
const headerNames = response.getHeaderNames();
// headerNames === ['foo', 'set-cookie'] copy

response.getHeaders() #

Returns a shallow copy of the current outgoing headers. Since a shallow copy is used, array values may be mutated without additional calls to various header-related http module methods. The keys of the returned object are the header names and the values are the respective header values. All header names are lowercase.

The object returned by the response.getHeaders() method does not prototypically inherit from the JavaScript Object . This means that typical Object methods such as obj.toString() , obj.hasOwnProperty() , and others are not defined and will not work .

response.setHeader('Foo', 'bar');
response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);
const




    
 headers = response.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } copy

response.hasHeader(name) #

Returns true if the header identified by name is currently set in the outgoing headers. The header name matching is case-insensitive.

const hasContentType = response.hasHeader('content-type'); copy

response.headersSent #

Boolean (read-only). True if headers were sent, false otherwise.

response.removeHeader(name) #

Removes a header that's queued for implicit sending.

response.removeHeader('Content-Encoding'); copy

response.req #

A reference to the original HTTP request object.

response.sendDate #

When true, the Date header will be automatically generated and sent in the response if it is not already present in the headers. Defaults to true.

This should only be disabled for testing; HTTP requires the Date header in responses.

response.setHeader(name, value) #

Returns the response object.

Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name. Non-string values will be stored without modification. Therefore, response.getHeader() may return non-string values. However, the non-string values will be converted to strings for network transmission. The same response object is returned to the caller, to enable call chaining.

response.setHeader('Content-Type', 'text/html'); copy

response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); copy

Attempting to set a header field name or value that contains invalid characters will result in a TypeError being thrown.

When headers have been set with response.setHeader() , they will be merged with any headers passed to response.writeHead() , with the headers passed to response.writeHead() given precedence.

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

If response.writeHead() method is called and this method has not been called, it will directly write the supplied header values onto the network channel without caching internally, and the response.getHeader() on the header will not yield the expected result. If progressive population of headers is desired with potential future retrieval and modification, use response.setHeader() instead of response.writeHead() .

response.setTimeout(msecs[, callback]) #

Sets the Socket's timeout value to msecs . If a callback is provided, then it is added as a listener on the 'timeout' event on the response object.

If no 'timeout' listener is added to the request, the response, or the server, then sockets are destroyed when they time out. If a handler is assigned to the request, the response, or the server's 'timeout' events, timed out sockets must be handled explicitly.

response.socket #

Reference to the underlying socket. Usually users will not want to access this property. In particular, the socket will not emit 'readable' events because of how the protocol parser attaches to the socket. After response.end() , the property is nulled.

import http from 'node:http';
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);const http = require('node:http');
const server = http.createServer((req, res) => {
  const ip = res.socket.remoteAddress;
  const port = res.socket.remotePort;
  res.end(`Your IP address is ${ip} and your source port is ${port}.`);
}).listen(3000);copy

This property is guaranteed to be an instance of the <net.Socket> class, a subclass of <stream.Duplex> , unless the user specified a socket type other than <net.Socket> .

response.statusCode #

When using implicit headers (not calling response.writeHead() explicitly), this property controls the status code that will be sent to the client when the headers get flushed.

response.statusCode = 404; copy

After response header was sent to the client, this property indicates the status code which was sent out.

response.statusMessage #

When using implicit headers (not calling response.writeHead() explicitly), this property controls the status message that will be sent to the client when the headers get flushed. If this is left as undefined then the standard message for the status code will be used.

response.statusMessage = 'Not found'; copy

After response header was sent to the client, this property indicates the status message which was sent out.

response.strictContentLength #

If set to true , Node.js will check whether the Content-Length header value and the size of the body, in bytes, are equal. Mismatching the Content-Length header value will result in an Error being thrown, identified by code: 'ERR_HTTP_CONTENT_LENGTH_MISMATCH' .

response.uncork() #

See writable.uncork() .

response.writableEnded #

Is true after response.end() has been called. This property does not indicate whether the data has been flushed, for this use response.writableFinished instead.

response.writableFinished #

Is true if all data has been flushed to the underlying system, immediately before the 'finish' event is emitted.

response.write(chunk[, encoding][, callback]) #

const earlyHintsLink = '</styles.css>; rel=preload; as=style';
response.writeEarlyHints({
  'link': earlyHintsLink,
const earlyHintsLinks = [
  '</styles.css>; rel=preload; as=style',
  '</scripts.js>; rel=preload; as=script',
response.writeEarlyHints({
  'link': earlyHintsLinks,
  'x-trace-id': 'id for diagnostics',
const earlyHintsCallback = () => console.log('early hints message sent');
response.writeEarlyHints({
  'link': earlyHintsLinks,
}, earlyHintsCallback); copy

const body = 'hello world';
response
  .writeHead(200, {
    'Content-Length': Buffer.byteLength(body),
    'Content-Type': 'text/plain',
  .end(body); copy

// Returns content-type = text/plain
const server = http.createServer((req, res) => {
  res.setHeader('Content-Type', 'text/html');
  res.setHeader('X-Foo', 'bar');
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

An IncomingMessage object is created by http.Server or http.ClientRequest and passed as the first argument to the 'request' and 'response' event respectively. It may be used to access response status, headers, and data.

Different from its socket value which is a subclass of <stream.Duplex> , the IncomingMessage itself extends <stream.Readable> and is created separately to parse and emit the incoming HTTP headers and payload, as the underlying socket may be reused multiple times in case of keep-alive.

Event: 'aborted' #

Emitted when the request has been aborted.

Event: 'close' #

const req = http.request({
  host: '127.0.0.1',
  port: 8080,
  method: 'POST',
}, (res) => {
  res.resume();
  res.on('end', () => {
    if (!res.complete)
      console.error(
        'The connection was terminated while the message was still being sent');
}); copy

// Prints something like:
// { 'user-agent': 'curl/7.22.0',
//   host: '127.0.0.1:8000',
//   accept: '*/*' }
console.log(request.headers); copy

// Prints something like:
// { 'user-agent': ['curl/7.22.0'],
//   host: ['127.0.0.1:8000'],
//   accept: ['*/*'] }
console.log(request.headersDistinct); copy

// Prints something like:
// [ 'user-agent',
//   'this is invalid because there can be only one',
//   'User-Agent',
//   'curl/7.22.0',
//   'Host',
//   '127.0.0.1:8000',
//   'ACCEPT',
//   '*/*' ]
console.log(request.rawHeaders); copy

GET /status?name=ryan HTTP/1.1
Accept: text/plain copy

new URL(request.url, `http://${request.headers.host}`); copy

$ node
> new URL(request.url, `http://${request.headers.host}`)
URL {
  href: 'http://localhost:3000/status?name=ryan',
  origin: 'http://localhost:3000',
  protocol: 'http:',
  username: '',
  password: '',
  host: 'localhost:3000',
  hostname: 'localhost',
  port: '3000',
  pathname: '/status',
  search: '?name=ryan',
  searchParams: URLSearchParams { 'name' => 'ryan' },
  hash: ''
} copy

Finishes the outgoing message. If any parts of the body are unsent, it will flush them to the underlying system. If the message is chunked, it will send the terminating chunk 0\r\n\r\n , and send the trailers (if any).

If chunk is specified, it is equivalent to calling outgoingMessage.write(chunk, encoding) , followed by outgoingMessage.end(callback) .

If callback is provided, it will be called when the message is finished (equivalent to a listener of the 'finish' event).

outgoingMessage.flushHeaders() #

outgoingMessage.getHeader(name) #

Gets the value of the HTTP header with the given name. If that header is not set, the returned value will be undefined .

outgoingMessage.getHeaderNames() #

Returns an array containing the unique names of the current outgoing headers. All names are lowercase.

outgoingMessage.getHeaders() #

Returns a shallow copy of the current outgoing headers. Since a shallow copy is used, array values may be mutated without additional calls to various header-related HTTP module methods. The keys of the returned object are the header names and the values are the respective header values. All header names are lowercase.

The object returned by the outgoingMessage.getHeaders() method does not prototypically inherit from the JavaScript Object . This means that typical Object methods such as obj.toString() , obj.hasOwnProperty() , and others are not defined and will not work.

outgoingMessage.setHeader('Foo', 'bar');
outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);
const headers = outgoingMessage.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } copy

outgoingMessage.hasHeader(name) #

Returns true if the header identified by name is currently set in the outgoing headers. The header name is case-insensitive.

const hasContentType = outgoingMessage.hasHeader('content-type'); copy

outgoingMessage.headersSent #

Read-only. true if the headers were sent, otherwise false .

outgoingMessage.pipe() #

outgoingMessage.removeHeader(name) #

Removes a header that is queued for implicit sending.

outgoingMessage.removeHeader('Content-Encoding'); copy

outgoingMessage.setHeader(name, value) #

Sets a single header value. If the header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings to send multiple headers with the same name.

outgoingMessage.setHeaders(headers) #

Returns the response object.

Sets multiple header values for implicit headers. headers must be an instance of Headers or Map , if a header already exists in the to-be-sent headers, its value will be replaced.

const headers = new Headers({ foo: 'bar' });
response.setHeaders(headers); copy

const headers = new Map([['foo', 'bar']]);
res.setHeaders(headers); copy

When headers have been set with outgoingMessage.setHeaders() , they will be merged with any headers passed to response.writeHead() , with the headers passed to response.writeHead() given precedence.

// Returns content-type = text/plain
const server = http.createServer((req, res




    
) => {
  const headers = new Headers({ 'Content-Type': 'text/html' });
  res.setHeaders(headers);
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('ok');
}); copy

outgoingMessage.setTimeout(msesc[, callback]) #

Once a socket is associated with the message and is connected, socket.setTimeout() will be called with msecs as the first parameter.

outgoingMessage.socket #

Reference to the underlying socket. Usually, users will not want to access this property.

After calling outgoingMessage.end() , this property will be nulled.

outgoingMessage.uncork() #

See writable.uncork()

outgoingMessage.writableCorked #

The number of times outgoingMessage.cork() has been called.

outgoingMessage.writableEnded #

Is true if outgoingMessage.end() has been called. This property does not indicate whether the data has been flushed. For that purpose, use message.writableFinished instead.

outgoingMessage.writableFinished #

Is true if all data has been flushed to the underlying system.

outgoingMessage.writableHighWaterMark #

The highWaterMark of the underlying socket if assigned. Otherwise, the default buffer level when writable.write() starts returning false ( 16384 ).

outgoingMessage.writableLength #

The number of buffered bytes.

outgoingMessage.writableObjectMode #

Always false .

outgoingMessage.write(chunk[, encoding][, callback]) #

requestListener <Function>

Returns: <http.Server>

Returns a new instance of http.Server .

The requestListener is a function which is automatically added to the 'request' event.

import http from 'node:http';
// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
server.listen(8000);const http = require('node:http');
// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
server.listen(8000);copy

import http from 'node:http';
// Create a local server to receive data from
const server = http.createServer();
// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
server.listen(8000);const http = require('node:http');
// Create a local server to receive data from
const server = http.createServer();
// Listen to the request event
server.on('request', (request, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
server.listen(8000);copy

Since most requests are GET requests without bodies, Node.js provides this convenience method. The only difference between this method and http.request() is that it sets the method to GET by default and calls req.end() automatically. The callback must take care to consume the response data for reasons stated in http.ClientRequest section.

The callback is invoked with a single argument that is an instance of http.IncomingMessage .

JSON fetching example:

http.get('http://localhost:8000/', (res) => {
  const { statusCode } = res;
  const contentType = res.headers['content-type'];
  let error;
  // Any 2xx status code signals a successful response but
  // here we're only checking for 200.
  if (statusCode !== 200) {
    error = new Error('Request Failed.\n' +
                      `Status Code: ${statusCode}`);
  } else if (!/^application\/json/.test(contentType)) {
    error = new Error('Invalid content-type.\n' +
                      `Expected application/json but received ${contentType}`);
  if (error) {
    console.error(error.message);
    // Consume response data to free up memory
    res.resume();
    return;
  res.setEncoding('utf8');
  let rawData = '';
  res.on('data', (chunk) => { rawData += chunk; });
  res.on('end', () => {
    try {
      const parsedData = JSON.parse(rawData);
      console.log(parsedData);
    } catch (e) {
      console.error(e.message);
}).on('error', (e) => {
  console.error(`Got error: ${e.message}`);
// Create a local server to receive data from
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    data: 'Hello World!',
server.listen(8000); copy

options in socket.connect() are also supported.

Node.js maintains several connections per server to make HTTP requests. This function allows one to transparently issue requests.

url can be a string or a URL object. If url is a string, it is automatically parsed with new URL() . If it is a URL object, it will be automatically converted to an ordinary options object.

If both url and options are specified, the objects are merged, with the options properties taking precedence.

The optional callback parameter will be added as a one-time listener for the 'response' event.

http.request() returns an instance of the http.ClientRequest class. The ClientRequest instance is a writable stream. If one needs to upload a file with a POST request, then write to the ClientRequest object.

import http from 'node:http';
import { Buffer } from 'node:buffer';
const postData = JSON.stringify({
  'msg': 'Hello World!',
const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  res.on('end', () => {
    console.log('No more data in response.');
req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
// Write data to request body
req.write(postData);
req.end();const http = require('node:http');
const postData = JSON.stringify({
  'msg': 'Hello World!',
const options = {
  hostname: 'www.google.com',
  port: 80,
  path: '/upload',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(postData),
const req = http.request(options, (res) => {
  console.log(`STATUS: ${res.statusCode}`);
  console




    
.log(`HEADERS: ${JSON.stringify(res.headers)}`);
  res.setEncoding('utf8');
  res.on('data', (chunk) => {
    console.log(`BODY: ${chunk}`);
  res.on('end', () => {
    console.log('No more data in response.');
req.on('error', (e) => {
  console.error(`problem with request: ${e.message}`);
// Write data to request body
req.write(postData);
req.end();copy

In the example req.end() was called. With http.request() one must always call req.end() to signify the end of the request - even if there is no data being written to the request body.

If any error is encountered during the request (be that with DNS resolution, TCP level errors, or actual HTTP parse errors) an 'error' event is emitted on the returned request object. As with all 'error' events, if no listeners are registered the error will be thrown.

There are a few special headers that should be noted.

Sending a 'Connection: keep-alive' will notify Node.js that the connection to the server should be persisted until the next request.

Sending a 'Content-Length' header will disable the default chunked encoding.

Sending an 'Expect' header will immediately send the request headers. Usually, when sending 'Expect: 100-continue', both a timeout and a listener for the 'continue' event should be set. See RFC 2616 Section 8.2.3 for more information.

Sending an Authorization header will override using the auth option to compute basic authentication.

Example using a URL as options :

const options = new URL('http://abc:[email protected]');
const req = http.request(options, (res) => {
  // ...
}); copy

In a successful request, the following events will be emitted in the following order:

In the case of a connection error, the following events will be emitted:

In the case of a premature connection close before the response is received, the following events will be emitted in the following order:

In the case of a premature connection close after the response is received, the following events will be emitted in the following order:

If req.destroy() is called before a socket is assigned, the following events will be emitted in the following order:

If req.destroy() is called before the connection succeeds, the following events will be emitted in the following order:

If req.destroy() is called after the response is received, the following events will be emitted in the following order:

If req.abort() is called before a socket is assigned, the following events will be emitted in the following order:

If req.abort() is called before the connection succeeds, the following events will be emitted in the following order:

If req.abort() is called after the response is received, the following events will be emitted in the following order:

Setting the timeout option or using the setTimeout() function will not abort the request or do anything besides add a 'timeout' event.

Passing an AbortSignal and then calling abort() on the corresponding AbortController will behave the same way as calling .destroy() on the request. Specifically, the 'error' event will be emitted with an error with the message 'AbortError: The operation was aborted' , the code 'ABORT_ERR' and the cause , if one was provided.

Performs the low-level validations on the provided name that are done when res.setHeader(name, value) is called.

Passing illegal value as name will result in a TypeError being thrown, identified by code: 'ERR_INVALID_HTTP_TOKEN' .

It is not necessary to use this method before passing headers to an HTTP request or response. The HTTP module will automatically validate such headers. Examples:

Example:

import { validateHeaderName } from 'node:http';
try {
  validateHeaderName('');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message); // --> 'Header name must be a valid HTTP token [""]'
}const { validateHeaderName } = require('node:http');
try {
  validateHeaderName('');
} catch (err) {
  console.error(err instanceof TypeError); // --> true
  console.error(err.code); // --> 'ERR_INVALID_HTTP_TOKEN'
  console.error(err.message); // --> 'Header name must be a valid HTTP token [""]'
}copy